# Voanews — 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 VOA Learning English lessons, programs, and vocabulary across all proficiency levels, search for specific content, and retrieve detailed lesson information with transcripts. Browse featured homepage content and explore lessons by category to find the perfect English learning materials for your level.

**Category:** Education | **Website:** [voanews.com/](https://voanews.com/) | **Docs:** [parse.bot/marketplace/2419912b-204c-49a3-9c49-b0c87b5a7853/voanews-com-api](https://parse.bot/marketplace/2419912b-204c-49a3-9c49-b0c87b5a7853/voanews-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/voanews/`
**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 category list

Fetch lessons for a specific category ID from the VOA site. Returns paginated article listings. The page parameter is 0-based. Use category IDs from known mappings (e.g. 3620 for News Words, 4456 for Everyday Grammar, 987 for Words and Stories).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Numeric category ID (e.g. '3620' for News Words, '4456' for Everyday Grammar, '987' for Words and Stories) |
| `page` | integer | No | Page offset for results (0-based) |

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

### Get homepage featured

Fetch featured stories and highlights from the VOA Learning English homepage. Returns currently promoted content items with their media type and status.

**Estimated cost:** Metered

_No parameters required._

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

### Get lesson detail

Get full details for a lesson or article, including transcript, vocabulary, and media links. Either article_id or url must be provided. The article ID can be extracted from any VOA Learning English article URL (the numeric portion before .html).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `article_id` | string | No | Numeric article ID (e.g. '5345471'). Can be obtained from search_lessons or get_category_list results. |
| `url` | string | No | Full URL of the lesson page (e.g. 'https://learningenglish.voanews.com/a/grammar-games-at-home-part-1-jeopardy/5345471.html') |

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

### Get level program list

Get a list of articles for a specific VOA Learning English program or level. Supports category-based programs (news_words, words_and_stories, everyday_grammar, everyday_grammar_tv, ask_a_teacher, english_at_the_movies, english_in_a_minute, how_to_pronounce, american_stories, arts_and_culture, science_and_technology, health_and_lifestyle, education_tips, learning_english_podcast, as_it_is) and static page programs (beginning_level, intermediate_level, advanced_level, us_history, americas_presidents, lets_teach_english, news_literacy, lets_learn_english_level_1, lets_learn_english_level_2, lets_learn_english_anna, americas_national_parks). Returns a single page of articles.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `program` | string | Yes | Program name identifier |

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

### Search lessons

Full-text search across VOA Learning English content by keyword. Results ordered by newest first. Paginates via integer page number. Each result includes article ID, title, URL, date, and thumbnail.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of results per page |
| `page` | integer | No | Page number (1-based) |
| `query` | string | Yes | Search keyword or phrase |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/voanews/search-lessons \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>","query":"<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.