# The Palace Museum — 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.

> Search and explore the Palace Museum's vast collection of artifacts organized by category and dynasty, then view detailed information about specific items. Discover historical objects spanning different periods and classifications to learn about the museum's treasures.

**Category:** Education | **Website:** [dpm.org.cn/](https://dpm.org.cn/) | **Docs:** [parse.bot/marketplace/96be3d60-6b72-4377-a36c-5fe6710f8795/dpm-org-cn-api](https://parse.bot/marketplace/96be3d60-6b72-4377-a36c-5fe6710f8795/dpm-org-cn-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/the-palace-museum/`
**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 collection item detail

Get full details for a single collection item including title, description, dynasty, category, artifact number, keywords (dimensions), and image URLs. The item_url parameter must be a detail page URL from search_collections results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item_url` | string | Yes | The full URL of the item detail page on dpm.org.cn, as returned in search_collections results detail_url field. |

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

### List categories

List all collection categories available in the Palace Museum digital database. Returns the full vocabulary of category objects (id plus Chinese name). No pagination, always returns all categories in one call.

**Estimated cost:** Metered

_No parameters required._

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

### List dynasties

List all dynasties and historical eras available as filters in the Palace Museum digital database. Returns the complete set of dynasty objects (id plus Chinese name) spanning from the Neolithic era through modern times. No pagination.

**Estimated cost:** Metered

_No parameters required._

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

### Search collections

Search the Palace Museum main collection by category and optional keyword. Returns paginated results with 12 items per page. Each item includes name, detail URL, thumbnail image, period, and category. Navigate from a summary to full details via the details() method.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category slug for filtering. |
| `keyword` | string | No | Search keyword to filter results within the category. |
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/the-palace-museum/search-collections \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","keyword":"<string>","page":"<integer>"}'
```

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