# Testbook — 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 discover exams, courses, test series, and articles across India's top government exam preparation platform, while browsing exam categories and checking upcoming live class schedules to plan your study journey. Get instant access to relevant study materials and learning opportunities tailored for competitive exams like UPSC, SSC, banking, and more.

**Category:** Education | **Website:** [testbook.com/](https://testbook.com/) | **Docs:** [parse.bot/marketplace/ba99ad77-3f79-4fb2-bdec-d63d279b7dcb/testbook-com-api](https://parse.bot/marketplace/ba99ad77-3f79-4fb2-bdec-d63d279b7dcb/testbook-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/testbook/`
**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 questions by topic

Fetch MCQ questions listed under a given topic on Testbook. The topic is identified by its URL slug (e.g. 'mcq-on-research-methodology--5eea6a0d39140f30f369e1a5'). Returns up to ~15 questions per topic page, including question text, multiple-choice options, correct answer, solution explanation, and the topic breadcrumb. The slug can be obtained from Testbook's /objective-questions listing pages where topic links follow the pattern '<topic-slug>--<topic-id>'. One round trip per call; no pagination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `language` | string | No | Language for results. Accepts: English, Hindi. |
| `topic_slug` | string | Yes | Topic URL slug including the tag ID suffix, as found on Testbook objective-questions pages (e.g. 'mcq-on-research-methodology--5eea6a0d39140f30f369e1a5', 'mcq-on-computer-graphics--5eea6a0939140f30f369da4d'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/testbook/get-questions-by-topic \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"language":"<string>","topic_slug":"<string>"}'
```

### Get upcoming classes

Get upcoming and live free classes/lessons for a given exam super group. Returns lessons with schedule, instructor details, and series information. Use category IDs from list_exam_categories as the super_group_id parameter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `language` | string | No | Language for results. Accepts: English, Hindi. |
| `limit` | integer | No | Maximum number of lessons to return. |
| `skip` | integer | No | Number of results to skip for pagination. |
| `super_group_id` | string | No | Super group ID from list_exam_categories endpoint (id field). Default is Teaching Exams. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/testbook/get-upcoming-classes \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"language":"<string>","limit":"<integer>","skip":"<integer>","super_group_id":"<string>"}'
```

### List exam categories

List all exam category super groups available on Testbook (e.g. SSC Exams, Banking Exams, Railways Exams, Teaching Exams, etc.). Each category includes its ID (usable as super_group_id in get_upcoming_classes), title, logo URL, and count of target exams within it.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `language` | string | No | Language for results. Accepts: English, Hindi. |

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

### Search

Global search across Testbook's content including exams (targets), courses, test series, tests, articles, quizzes, videos, free tests, previous year papers, and goal cards. Returns result counts per content type and actual result items.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `language` | string | No | Language for results. Accepts: English, Hindi. |
| `search_on` | string | No | Comma-separated list of content types to search. Accepted values: targets, courses, testSeries, tests, articles, quizzes, videos, freeTests, pyp, goalCards. |
| `term` | string | Yes | Search query term (e.g. 'SSC', 'Banking', 'Railways'). |

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