# Scholarships — 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 and browse the Scholarships.com directory by category — including academic major, residence state, ethnicity, gender, school year, and deadline. Retrieve scholarship listings within any category and subcategory, and fetch full details for individual scholarships including award amounts, eligibility criteria, application deadlines, and application links.

**Category:** Education | **Website:** [scholarships.com/](https://scholarships.com/) | **Docs:** [parse.bot/marketplace/9dccd551-0b32-432f-ac0c-c070031ba36d/scholarships-com-api](https://parse.bot/marketplace/9dccd551-0b32-432f-ac0c-c070031ba36d/scholarships-com-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/scholarships/`
**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 scholarship detail

Returns full details for a specific scholarship including description, amount, deadline, number of awards available, eligibility criteria, and application URL when available. Uses the scholarship slug from list_scholarships_in_category results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `scholarship_slug` | string | Yes | Slug identifier for the scholarship, as returned in list_scholarships_in_category results. |

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

### Get scholarship directory categories

Returns all top-level scholarship directory category types (Academic Major, Residence State, Ethnicity, Race, Gender, etc.) available for filtering scholarships. No parameters required. Each category has a slug usable with list_subcategories.

**Estimated cost:** Metered

_No parameters required._

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

### List all states

Convenience endpoint that returns all US states and territories available for filtering scholarships by residence state. Equivalent to calling list_subcategories with category_slug 'residence-state'. Each state has a slug usable with list_scholarships_in_category.

**Estimated cost:** Metered

_No parameters required._

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

### List scholarships in category

Returns a list of scholarships within a specific category and subcategory combination. Each scholarship includes name, slug, and URL. Uses slugs from get_scholarship_directory_categories and list_subcategories. Results are not paginated; all scholarships for the subcategory are returned in a single response.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_slug` | string | Yes | Slug of the top-level category (e.g. residence-state, academic-major, ethnicity) |
| `subcategory_slug` | string | Yes | Slug of the subcategory (e.g. california, accounting, afghan). Obtained from list_subcategories results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/scholarships/list-scholarships-in-category \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_slug":"<string>","subcategory_slug":"<string>"}'
```

### List subcategories

Lists subcategories for a given top-level category. For example, returns all academic majors for category 'academic-major', all states for 'residence-state', or all ethnicities for 'ethnicity'. Each subcategory has a slug usable with list_scholarships_in_category.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_slug` | string | Yes | Slug of the top-level category from get_scholarship_directory_categories (e.g. academic-major, residence-state, ethnicity, race, gender, school-year, deadline, special-attributes, physical-disabilities, scholarship-amount, act-score, age, artistic-ability, athletic-ability, employer, financial-need, grade-point-average, honors-organization, military-affiliation, number-of-scholarships-available, religion, sat-score, school-attendance-state, student-organization) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/scholarships/list-subcategories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_slug":"<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.