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

> Access Terra Caribbean's real estate marketplace data programmatically. Search and filter property listings by location, parish, zoning, price, and amenities across Barbados, Grenada, St. Lucia, and Trinidad & Tobago. Retrieve full listing details, browse blog content by country, and calculate estimated mortgage payments.

**Category:** Real Estate | **Website:** [terracaribbean.com/](https://terracaribbean.com/) | **Docs:** [parse.bot/marketplace/f922a9aa-569e-4abd-9851-846f44448dc2/terracaribbean-com-api](https://parse.bot/marketplace/f922a9aa-569e-4abd-9851-846f44448dc2/terracaribbean-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/terracaribbean/`
**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

### Calculate mortgage

Calculate estimated monthly mortgage payments based on loan amount, annual interest rate, and term length. Uses standard amortization formula. Returns monthly payment, total amount paid over the term, and total interest paid.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amount` | number | Yes | Mortgage loan amount in dollars. |
| `rate` | number | Yes | Annual interest rate as a percentage (e.g. 5.5 for 5.5%). |
| `years` | integer | Yes | Length of mortgage in years. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/terracaribbean/calculate-mortgage \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount":"<number>","rate":"<number>","years":"<integer>"}'
```

### Get amenities

Get list of available property amenities. These values can be used in the amenities filter of search_properties.

**Estimated cost:** Metered

_No parameters required._

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

### Get blog posts

List blog posts for a specific Caribbean location. Returns titles, URLs, publication dates, and text excerpts. Not all location slugs have blog categories; verified working values are 'barbados' and 'grenada'.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | No | Location name slug. Verified working values: 'barbados', 'grenada'. |

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

### Get locations

Get all supported Caribbean territories and their country codes. Returns the four locations covered by Terra Caribbean: Barbados, Grenada, Saint Lucia, and Trinidad & Tobago.

**Estimated cost:** Metered

_No parameters required._

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

### Get parishes

Get list of parishes (administrative regions) for a country. These values can be used in the regions filter of search_properties. Each country has its own set of parishes.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country_code` | string | No | Country code for which to retrieve parishes. |

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

### Get property details

Retrieve full details for a single property listing by its URL. Returns title, formatted price, full description, photo gallery URLs, reference number, and office contact phone. The URL is typically obtained from search_properties results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full URL of the property listing page, as returned in search_properties results. |

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

### Search properties

Full-text and filtered search across Caribbean property listings. Returns paginated summaries sorted by price ascending. Each result includes listing_id, price, location, and property attributes. Pagination is manual via offset; each page returns up to `limit` items. Note: combining regions and amenities filters in one call may cause upstream server errors due to a known site limitation; use them separately for reliable results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amenities` | string | No | Comma-separated list of amenities to filter by (e.g. 'Beachfront,Pool'). Values from get_amenities endpoint. |
| `baths_min` | string | No | Minimum number of bathrooms. |
| `beds_min` | string | No | Minimum number of bedrooms. |
| `country_code` | string | No | Country code for the search territory. |
| `keyword` | string | No | Free-text search against property titles and descriptions. |
| `limit` | integer | No | Number of results per page. |
| `listing_type` | string | No | Whether to search properties for sale or rent. |
| `offset` | integer | No | Result offset for pagination. |
| `price_max` | string | No | Maximum price in USD. |
| `price_min` | string | No | Minimum price in USD. |
| `regions` | string | No | Comma-separated list of parishes or regions to filter by (e.g. 'St. James,Christ Church'). Values from get_parishes endpoint. |
| `zoning` | string | No | Property category filter. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/terracaribbean/search-properties \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amenities":"<string>","baths_min":"<string>","beds_min":"<string>","country_code":"<string>","keyword":"<string>","limit":"<integer>","listing_type":"<string>","offset":"<integer>","price_max":"<string>","price_min":"<string>","regions":"<string>","zoning":"<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.