# YÖK Atlas — 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 Turkey's official higher education database via YÖK Atlas. Search and filter universities and degree programs by city, score type, and field of study; retrieve admission statistics, success rankings, quotas, tuition details, graduate exam outcomes, and full university profiles.

**Category:** Education | **Website:** [yokatlas.yok.gov.tr/](https://yokatlas.yok.gov.tr/) | **Docs:** [parse.bot/marketplace/bdd36f43-2790-4426-8c7d-0706890bf033/y-k-atlas-api](https://parse.bot/marketplace/bdd36f43-2790-4426-8c7d-0706890bf033/y-k-atlas-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/yok-atlas/`
**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 graduate success

Get graduate success statistics for central exams (TUS, DUS, KPSS, etc.).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exam_id` | string | Yes | Exam ID: 1=TUS, 4=DUS, 6=KPSS etc. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yok-atlas/get-graduate-success \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"exam_id":"<string>"}'
```

### Get program details

Get detailed statistics and info for a specific program (scores, ranks, gender distribution, academic staff, etc.). Program codes can be obtained from get_university_programs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `level` | string | No | Education level: 'lisans' or 'onlisans' |
| `panels` | string | No | Comma-separated panel IDs to fetch (e.g., '1000_1,1000_2'). If not specified, all panels are fetched. |
| `program_code` | string | Yes | ÖSYM program code (e.g., '100110645') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yok-atlas/get-program-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"level":"<string>","panels":"<string>","program_code":"<string>"}'
```

### Get university detail

Get university-level detailed info (name, type, city, website, address, logo). Uses the university ID from list_universities endpoint.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `university_id` | string | Yes | University ID from list_universities (e.g., '173499', '100259') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yok-atlas/get-university-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"university_id":"<string>"}'
```

### Get university programs

Get all programs offered by a specific university. Uses the internal YÖK Atlas university code (e.g., 1001 for Bolu Abant İzzet Baysal Üniversitesi). University codes can be retrieved from the list_universities endpoint.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `level` | string | No | Education level: 'lisans' (bachelor) or 'onlisans' (associate) |
| `university_id` | string | Yes | YÖK Atlas internal university code (e.g., '1001', '1002') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yok-atlas/get-university-programs \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"level":"<string>","university_id":"<string>"}'
```

### List cities

List all Turkish cities (and some international locations such as KIBRIS, BOSNA-HERSEK) that have universities. City codes can be used as filters in the search_programs endpoint. The list is not paginated.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yok-atlas/list-cities \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### List programs

List all program groups (fields of study) available in the system with their IDs, names, and associated score types. Program group IDs can be used as filters in the search_programs endpoint. The list is not paginated.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yok-atlas/list-programs \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### List universities

List all Turkish universities with their internal IDs and names. Returns the complete roster of universities available in the YÖK Atlas system. The list is not paginated — all universities are returned in a single response.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yok-atlas/list-universities \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Search

Global search for universities and programs by keyword.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `term` | string | Yes | Search keyword (e.g., 'bilgisayar', 'tıp') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yok-atlas/search \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"term":"<string>"}'
```

### Search programs

Search and filter university programs with pagination. Returns detailed program information including admission scores, success ranks, quotas, tuition fees, scholarship status, and more. All filter parameters are optional; omitting all filters returns all programs sorted by success rank ascending. Supports pagination with zero-based page numbers.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_code` | string | No | City code to filter by (from list_cities, e.g. '34' for İstanbul). |
| `direction` | string | No | Sort direction. |
| `page` | integer | No | Zero-based page number for pagination. |
| `program_group_id` | string | No | Program group ID to filter by (from list_programs). |
| `score_type` | string | No | Score type filter. |
| `size` | integer | No | Number of results per page (max observed: 100). |
| `sort_by` | string | No | Field to sort by. |
| `university_id` | string | No | University ID to filter by (from list_universities). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yok-atlas/search-programs \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"city_code":"<string>","direction":"<string>","page":"<integer>","program_group_id":"<string>","score_type":"<string>","size":"<integer>","sort_by":"<string>","university_id":"<string>"}'
```

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