# Craigslist (craigslist.org) — 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 retrieve Craigslist listings for apartments, vehicles, jobs, services, and other categories across all regional sites to find exactly what you're looking for. Get detailed information about specific listings, browse by location and category, and compare options all in one place.

**Category:** Marketplaces | **Website:** [craigslist.org/](https://craigslist.org/) | **Docs:** [parse.bot/marketplace/812bee25-ff7f-46dc-bb63-7b36811ed6ba/craigslist-org-api](https://parse.bot/marketplace/812bee25-ff7f-46dc-bb63-7b36811ed6ba/craigslist-org-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/craigslist/`
**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 categories

Retrieve the complete mapping of Craigslist category codes to display names. Category codes are used as the category parameter in search_listings. Covers housing, vehicles, for-sale, jobs, services, community, and gigs.

**Estimated cost:** Metered

_No parameters required._

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

### Get listing detail

Get full details for a specific Craigslist listing by its complete URL. The URL must include the subarea and category path segments as returned by search_listings (e.g., 'https://newyork.craigslist.org/brk/bik/d/listing-slug/1234567.html'). Expired or removed listings return a stale_input error.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full Craigslist listing URL including subarea and category path (e.g., 'https://newyork.craigslist.org/brk/bik/d/brooklyn-kent-girls-bike/7905644978.html'). Obtain from search_listings results. |

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

### Get sites

Retrieve all Craigslist regional sites worldwide. Each site includes its hostname (used in search_listings), geographic coordinates, country, region, and available sub-areas. This is the reference endpoint for discovering valid site hostnames.

**Estimated cost:** Metered

_No parameters required._

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

### Search listings

Search for listings on a specific Craigslist site. Returns results from the Craigslist search API with full listing URLs suitable for get_listing_detail. Supports all category codes from get_categories. Results include posting ID, title, price, location, images, and a direct URL to the listing page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category code from get_categories (e.g., 'apa' for apartments, 'cta' for cars+trucks, 'sss' for all for sale, 'jjj' for all jobs, 'bbb' for all services, 'ggg' for all gigs, 'ccc' for all community, 'mis' for missed connections). |
| `has_image` | boolean | No | Filter to listings with images only. |
| `limit` | integer | No | Maximum number of results to return. |
| `max_price` | integer | No | Maximum price filter in dollars. |
| `min_price` | integer | No | Minimum price filter in dollars. |
| `offset` | integer | No | Offset for pagination (number of results to skip). |
| `posted_today` | boolean | No | Filter to listings posted today only. |
| `query` | string | No | Search query text to filter listings. |
| `site` | string | Yes | Craigslist site hostname (e.g., 'newyork.craigslist.org'). The subdomain portion must match a Hostname value from get_sites. |
| `sort` | string | No | Sort order for results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/craigslist/search-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","has_image":"<boolean>","limit":"<integer>","max_price":"<integer>","min_price":"<integer>","offset":"<integer>","posted_today":"<boolean>","query":"<string>","site":"<string>","sort":"<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.