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

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

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/josaa/`
**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 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.beta.paywithlocus.com/api/wrapped/credits/josaa/get-institute-list \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/josaa/get-opening-closing-ranks \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/josaa/get-previous-years-ranks \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/josaa/get-seat-matrix \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"branch":"<string>","inst_type":"<string>","institute":"<string>"}'
```

## Next steps

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