# Fragrantica — 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 discover perfumes with detailed information including fragrance notes, accords, and ratings, while exploring curated brands and note collections. Browse Fragrantica's comprehensive perfume catalog to find scents based on specific characteristics and community feedback.

**Category:** E-commerce | **Website:** [fragrantica.com/](https://fragrantica.com/) | **Docs:** [parse.bot/marketplace/366d90c1-f1bc-44ac-acb4-d21d2575ee6c/fragrantica-com-api](https://parse.bot/marketplace/366d90c1-f1bc-44ac-acb4-d21d2575ee6c/fragrantica-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/fragrantica/`
**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 perfume details

Get detailed information for a specific perfume by its full Fragrantica URL. Returns name, brand, fragrance notes pyramid (top/middle/base), main accords with intensity, rating, and description. Requires the complete URL path including the numeric perfume ID.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full URL of the perfume page on Fragrantica (e.g. 'https://www.fragrantica.com/perfume/Chanel/Chanel-No-5-Eau-de-Parfum-40069.html') |

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

### List brands

List perfume brands/designers filtered by first letter. Returns an array of brand names and their Fragrantica URLs for the given letter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `letter` | string | No | Single letter A-Z to filter brands by first character |

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

### List notes

List all fragrance notes categorized by group (e.g. Citrus, Flowers, Woods). Returns categories each containing an array of notes with name, URL, and image. No input parameters required.

**Estimated cost:** Metered

_No parameters required._

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

### Search perfumes

Full-text search over Fragrantica's perfume database via Algolia. Returns paginated results with perfume name, designer, year, rating, gender, and thumbnail. The API key is fetched dynamically from the site on first call.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Results per page (max 100) |
| `page` | integer | No | Page number (0-based) |
| `query` | string | Yes | Search keyword (e.g. 'chanel', 'rose', 'dior') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/fragrantica/search-perfumes \
  -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://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.