# Tori — 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 Finland's largest second-hand marketplace for listings across multiple categories, filter by specific items like refurbished phones, and retrieve detailed product information along with seller details. Access real-time data from Tori.fi to find used goods, compare prices, and contact sellers directly.

**Category:** Marketplaces | **Website:** [tori.fi/](https://tori.fi/) | **Docs:** [parse.bot/marketplace/c51efdf8-cea2-4d0d-8380-1d9a7204d4ea/tori-fi-api](https://parse.bot/marketplace/c51efdf8-cea2-4d0d-8380-1d9a7204d4ea/tori-fi-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-tori-fi-api-c51efdf8/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_item_details

Retrieve comprehensive details for a single listing by its numeric ID. Returns structured product data including description, brand, images, location (municipality and region codes), and seller name. Data is extracted from embedded structured-data markup on the listing page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item_id` | string | Yes | The unique numeric ID of the listing (e.g. '42648879'). Obtain from search_listings or search_telephones results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tori-fi-api-c51efdf8/get_item_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"item_id":"<string>"}'
```

### search_listings

Full-text search over Tori.fi recommerce listings. Filters by category hierarchy (category → sub_category → product_category) using dotted notation IDs. Returns a page of listing summaries; paginates via page number. When fetch_details is true, each item is enriched with description, location, and seller info (capped at 50 items per call, slower).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Top-level category ID in dotted notation. Confirmed values: '0.76' (Antiikki ja taide), '0.90' (Auto/vene/moottoripyörätarvikkeet), '0.93' (Elektroniikka ja kodinkoneet), '0.77' (Eläimet ja eläintarvikkeet), '0.78' (Koti ja sisustus), '0.68' (Lapset ja vanhemmat), '0.91' (Liiketoiminta ja palvelut), '0.67' (Piha ja remontointi), '0.69' (Urheilu ja ulkoilu), '0.71' (Vaatteet, kosmetiikka ja asusteet). |
| `fetch_details` | boolean | No | Whether to fetch full details (description, location, seller) for each item. Makes one additional request per item; limited to 50 items per call. |
| `page` | integer | No | Page number for pagination. |
| `product_category` | string | No | Product category ID in dotted notation (level 2 prefix + parent chain + product-id). Example: '2.93.3217.39' (Matkapuhelimet). |
| `query` | string | No | Search keyword matching listing titles and descriptions (e.g. 'puhelin', 'OnePlus'). |
| `sub_category` | string | No | Sub-category ID in dotted notation (level 1 prefix + parent + sub-id). Example: '1.93.3217' (Puhelimet ja tarvikkeet under Elektroniikka). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tori-fi-api-c51efdf8/search_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","fetch_details":"<boolean>","page":"<integer>","product_category":"<string>","query":"<string>","sub_category":"<string>"}'
```

### search_telephones

Search for mobile phones (Matkapuhelimet) in the recommerce section. A convenience shortcut that searches product category 2.93.3217.39. Returns paginated listing summaries identical in shape to search_listings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tori-fi-api-c51efdf8/search_telephones \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```