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

> Track top-performing iOS apps across categories with detailed insights on rankings, monetization models, ratings, revenue estimates, and user demographics. Monitor app performance metrics and discover trending applications by category to stay informed about the competitive app market landscape.

**Category:** Developer Tools | **Website:** [app.appfigures.com/top-apps/ios-app-store/united-states/iphone/top-overall](https://app.appfigures.com/top-apps/ios-app-store/united-states/iphone/top-overall) | **Docs:** [parse.bot/marketplace/f47338f8-3097-4cda-a68d-6a3b564ac506/app-appfigures-com-api](https://parse.bot/marketplace/f47338f8-3097-4cda-a68d-6a3b564ac506/app-appfigures-com-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/appfigures/`
**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 app details

Retrieve comprehensive details for a specific app by its Appfigures product ID (obtained from get_top_apps results). Returns full app metadata including description, monetization model, ratings, monthly download and revenue estimates, user demographics, supported countries and languages, categories, screenshots, and version history. One round-trip per app; batch lookups are not supported.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Appfigures product ID (the 'id' field from get_top_apps results). |

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

### Get categories

List all available iOS App Store categories with their URL slugs and internal IDs. Returns the complete category vocabulary; use slug values as the 'category' parameter in get_top_apps. The list is static and does not paginate.

**Estimated cost:** Metered

_No parameters required._

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

### Get top apps

Retrieve the top-ranked apps for a given iOS App Store category. Returns up to 200 apps for grossing lists and up to 500 for free/paid lists. Each result includes rank position, app identity, developer, and price. The response includes metadata about the category and ranking timestamp. Paginate client-side by adjusting limit; server returns a single snapshot per request.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category slug for the ranking list. |
| `country` | string | No | Country slug for the storefront (e.g. 'united-states', 'united-kingdom', 'japan', 'germany'). |
| `device` | string | No | Device type. |
| `limit` | integer | No | Maximum number of apps to return (up to 200 for grossing, 500 for free/paid). |
| `list_type` | string | No | Type of ranking list. |
| `store` | string | No | App store identifier. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/appfigures/get-top-apps \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","country":"<string>","device":"<string>","limit":"<integer>","list_type":"<string>","store":"<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.