# Tarva — 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 compare Porsche and Ferrari listings while viewing detailed VIN-decoded specifications, pricing history, and real-time market trends to find your ideal luxury sports car. Access comprehensive market data and listing information all in one place to make informed buying decisions.

**Category:** Automotive | **Website:** [tarva.io/](https://tarva.io/) | **Docs:** [parse.bot/marketplace/6fd21523-78d2-450d-aa06-ff9ce4f5edb8/tarva-io-api](https://parse.bot/marketplace/6fd21523-78d2-450d-aa06-ff9ce4f5edb8/tarva-io-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/tarva/`
**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 listing

Get full details for a single listing by its short ID. Returns comprehensive vehicle information including technical data, specs, listing URL, dealer info, and condition details. One network round-trip per call.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `short_id` | string | Yes | Short ID of the listing (e.g. 'CXMwmDmi'). Obtained from search_listings results. |

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

### Get market data

Get market overview data including tracked models with median prices, active listing counts, 30-day price changes, and monthly price trends. Covers popular Porsche GT and Ferrari models.

**Estimated cost:** Metered

_No parameters required._

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

### Lookup vin

Look up a Porsche or Ferrari vehicle by VIN. Returns decoded vehicle information including make, model, year, generation, exterior color, technical data (body dimensions, engine specs, drivetrain, performance), and any associated listing or key factory options.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `vin` | string | Yes | 17-character Vehicle Identification Number (VIN) for a Porsche GT or Ferrari vehicle. Alphanumeric, excluding letters I, O, Q. |

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

### Search listings

Search Porsche and Ferrari listings with filters for make, model, generation, transmission, color, specs, and status. Results are paginated and sortable. Returns listing summaries with price, location, mileage, and key specifications.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `colors` | string | No | Filter by color family (e.g. 'Black', 'Blue', 'Red', 'White', 'Grey', 'Silver', 'Green', 'Yellow', 'Orange', 'Purple', 'PTS'). |
| `generations` | string | No | Filter by generation code (e.g. '992.1', '992.2', '991.1', '718'). |
| `makes` | string | No | Filter by make. Accepted values: porsche, ferrari. |
| `models` | string | No | Filter by model name (e.g. '911 GT3', '296 GTB', 'Cayman GT4'). Must match model names returned in listings. |
| `page` | integer | No | Page number for pagination. |
| `page_size` | integer | No | Number of results per page (max 24). |
| `sort` | string | No | Sort order for results. |
| `specs` | string | No | Filter by spec/option name (e.g. 'PCCB', 'Full Bucket Seats', 'Front Axle Lift', 'Weissach Package'). |
| `status` | string | No | Listing status filter. |
| `transmissions` | string | No | Filter by transmission type. Accepted values: Automatic, Manual. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/tarva/search-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"colors":"<string>","generations":"<string>","makes":"<string>","models":"<string>","page":"<integer>","page_size":"<integer>","sort":"<string>","specs":"<string>","status":"<string>","transmissions":"<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.