API Documentation

Everything you need to integrate ScoutAPI into your AI agents and automation tools.

Getting Started

ScoutAPI exposes a single endpoint that returns structured marketplace data. Send a POST request with your search parameters and receive JSON results.

POST /api/scrape

Request Format

// Single platform
{
  "platform": "craigslist",
  "query": "iphone 15",
  "location": "sfbay",
  "max_results": 50
}

// Multi-platform (results from each independently)
{
  "platforms": ["craigslist", "facebook", "offerup"],
  "query": "iphone 15",
  "location": "sfbay",
  "max_results": 20
}

Field	Type	Required	Description
platform	string	Yes	Marketplace to scrape: `"craigslist"`, `"facebook"`, `"offerup"`, or `"mercari"`
query	string	Yes	Search term
location	string	Yes	Craigslist region code (see below)
max_results	number	No	1-100, default 50

platform

stringRequired

Marketplace to scrape. Currently: "craigslist"

query

stringRequired

Search term

location

stringRequired

Craigslist region code (see below)

max_results

numberOptional

1-100, default 50

Response Format

{
  "success": true,
  "results": [
    {
      "id": "7299847294",
      "title": "iPhone 15 Pro 256GB - Mint Condition",
      "price": 850,
      "location": "Mission District, SF",
      "url": "https://sfbay.craigslist.org/sfc/mob/d/...",
      "posted": "2 hours ago",
      "platform": "craigslist",
      "image": "https://images.craigslist.org/..."
    }
  ],
  "count": 23,
  "query_time_ms": 847
}

Error Responses

{
  "success": false,
  "error": {
    "code": "SCRAPE_FAILED",
    "message": "Could not retrieve listings from Craigslist"
  }
}

Code	Description
INVALID_REQUEST	Missing required fields
UNSUPPORTED_PLATFORM	Platform not yet available
INVALID_LOCATION	Unrecognized location code
TIMEOUT	Scrape exceeded 30s timeout
SCRAPE_FAILED	General scraping error

INVALID_REQUEST

Missing required fields

UNSUPPORTED_PLATFORM

Platform not yet available

INVALID_LOCATION

Unrecognized location code

TIMEOUT

Scrape exceeded 30s timeout

SCRAPE_FAILED

General scraping error

Code Samples

cURL

curl -X POST http://localhost:3000/api/scrape \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "craigslist",
    "query": "macbook pro",
    "location": "sfbay",
    "max_results": 10
  }'

JavaScript (fetch)

const response = await fetch("/api/scrape", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    platform: "craigslist",
    query: "macbook pro",
    location: "sfbay",
    max_results: 10
  })
});

const data = await response.json();
console.log(data.results);

Python (requests)

import requests

response = requests.post("http://localhost:3000/api/scrape", json={
    "platform": "craigslist",
    "query": "macbook pro",
    "location": "sfbay",
    "max_results": 10
})

data = response.json()
for listing in data["results"]:
    print(f"{listing['title']} - $" + str(listing['price']))

Supported Platforms

Platform	Coverage	Local Pickup	Shipping	Best For
Craigslist	Regional	Yes	No	Local deals, vehicles
Facebook	Regional	Yes	Sometimes	General marketplace
OfferUp	National	Yes	Yes	Mobile-first buyers
Mercari	National	No	Yes	Shipped goods, collectibles

Supported Locations

sfbaylosangelesnewyorkchicagoseattleportlanddenveraustinbostonmiamidallashoustonatlantaphoenixsandiegominneapolisdetroitphiladelphiawashingtondcorlando