# Kys Udiseplus — 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 for schools across India by geographic region and management type, then access detailed information about any school including academic performance, facilities, and enrollment data. Navigate through states, districts, and blocks to find schools that match your criteria and compare their profiles.

**Category:** Education | **Website:** [kys.udiseplus.gov.in/](https://kys.udiseplus.gov.in/) | **Docs:** [parse.bot/marketplace/75b66f72-2971-432f-8966-ed1cc64092fa/kys-udiseplus-gov-in-api](https://parse.bot/marketplace/75b66f72-2971-432f-8966-ed1cc64092fa/kys-udiseplus-gov-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/kys-udiseplus/`
**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 academic years

Fetch the list of academic years available in the system. Returns year IDs and descriptions used as parameters in other endpoints. The list is small (typically 5-6 entries) and does not paginate.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kys-udiseplus/get-academic-years \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get blocks

Fetch the list of blocks for a given district. Use the internal districtId from get_districts, NOT the UDISE district code. Returns block IDs and names for finer-grained geographic filtering.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `district_id` | integer | Yes | Internal district ID from get_districts endpoint (e.g. 1601 for East Delhi). |
| `year_id` | integer | No | Year ID from get_academic_years. Defaults to 0 (latest/Real Time). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kys-udiseplus/get-blocks \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"district_id":"<integer>","year_id":"<integer>"}'
```

### Get categories

Fetch school categories (e.g. Primary, Upper Primary, Secondary, Higher Secondary). Returns category IDs and descriptions. The list is fixed (~10 entries) and does not paginate.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kys-udiseplus/get-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get districts

Fetch the list of districts for a given state. Use the internal stateId from get_states, NOT the UDISE state code. Returns district IDs and names needed for get_blocks and school lookups.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `state_id` | integer | Yes | Internal state ID from get_states endpoint (e.g. 107 for Delhi, 136 for Telangana). |
| `year_id` | integer | No | Year ID from get_academic_years. Defaults to 0 (latest/Real Time). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kys-udiseplus/get-districts \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"state_id":"<integer>","year_id":"<integer>"}'
```

### Get managements

Fetch school management types (e.g. Department of Education, Government Aided, Private Unaided). Returns management IDs and names. The list is fixed (~17 entries) and does not paginate.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kys-udiseplus/get-managements \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get school details

Get comprehensive details for a specific school including profile, facility, statistics, and report card information. Aggregates data from four sub-endpoints into a single response. The school_id is the UDISE school code (numeric). Some sub-sections may be absent if the school has not reported that data.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `school_id` | integer | Yes | UDISE school ID (numeric code identifying the school, e.g. 5420344). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kys-udiseplus/get-school-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"school_id":"<integer>"}'
```

### Get states

Fetch the list of all states and union territories. Returns internal stateId values needed for get_districts and other regional endpoints. Includes special entities like Kendriya Vidyalaya Sanghathan and Navodaya Vidyalaya Samiti.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year_id` | integer | No | Year ID from get_academic_years. Defaults to 0 (latest/Real Time). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kys-udiseplus/get-states \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"year_id":"<integer>"}'
```

### Search schools by region

Search for schools based on regional filters. Requires state_id and district_id (internal IDs from get_states/get_districts). Returns school statistics and a list of schools in the 'content' field.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `block_id` | string | No | Block ID from get_blocks |
| `category_id` | string | No | Category ID from get_categories |
| `cluster_id` | string | No | Cluster ID |
| `district_id` | integer | Yes | Internal district ID from get_districts (e.g., 1601 for East Delhi) |
| `management_id` | string | No | Management ID from get_managements |
| `state_id` | integer | Yes | Internal state ID from get_states (e.g., 107 for Delhi) |
| `village_id` | string | No | Village ID |
| `year_id` | integer | No | Year ID. Defaults to 0 (latest). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kys-udiseplus/search-schools-by-region \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"block_id":"<string>","category_id":"<string>","cluster_id":"<string>","district_id":"<integer>","management_id":"<string>","state_id":"<integer>","village_id":"<string>","year_id":"<integer>"}'
```

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