ShelfRun API

Extract e-commerce product data from any online store. One API call. Standardized output.

Quick Start

Get product data from any store in 30 seconds:

1. Get your API key from the dashboard

2. Scan any store:

curl -X POST https://api.shelfrun.com/v1/quickscan \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sr_live_YOUR_KEY" \
  -d '{"url": "allbirds.com"}'

3. Get back standardized products:

{
  "url": "allbirds.com",
  "platform": "shopify",
  "store_name": "Allbirds",
  "products_found": 127,
  "products": [
    {
      "product_id": "7654321",
      "name": "Tree Runner",
      "price": 98.0,
      "currency": "USD",
      "in_stock": true,
      "image_url": "https://cdn.allbirds.com/...",
      "url": "https://allbirds.com/products/tree-runner"
    }
  ]
}

Authentication

All /v1/* endpoints require an API key passed via the X-API-Key header.

curl https://api.shelfrun.com/v1/stores \
  -H "X-API-Key: sr_live_YOUR_KEY"

Keep your API key secret. It's shown once at creation. Revoke compromised keys immediately from the dashboard.

Rate Limits

60 requests per minute per API key. Exceeding this returns 429 Too Many Requests.

API Endpoints

POST/v1/quickscan1 credit

Scan a URL and extract products in one call. No store creation needed.

curl -X POST https://api.shelfrun.com/v1/quickscan \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sr_live_YOUR_KEY" \
  -d '{"url": "nike.com"}'

POST/api/scanfree

Detect platform, capabilities, and estimated product count. No API key needed.

curl -X POST https://api.shelfrun.com/api/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "shopify-store.com"}'

GET/v1/stores

List all monitored stores.

curl https://api.shelfrun.com/v1/stores -H "X-API-Key: sr_live_YOUR_KEY"

POST/v1/stores

Add a store to monitor. Auto-detects platform.

curl -X POST https://api.shelfrun.com/v1/stores \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sr_live_YOUR_KEY" \
  -d '{"url": "example-store.com", "sync_frequency": "daily"}'

POST/v1/scrape/{store_id}1+ credits

Trigger a full scrape for a store. Credits deducted based on store complexity.

curl -X POST https://api.shelfrun.com/v1/scrape/STORE_ID \
  -H "X-API-Key: sr_live_YOUR_KEY"

GET/v1/stores/{store_id}/products

Get latest products. Supports JSON and CSV output.

# JSON (default)
curl https://api.shelfrun.com/v1/stores/STORE_ID/products \
  -H "X-API-Key: sr_live_YOUR_KEY"

# CSV
curl "https://api.shelfrun.com/v1/stores/STORE_ID/products?format=csv" \
  -H "X-API-Key: sr_live_YOUR_KEY" -o products.csv

JavaScript SDK

For JS/TS apps, use our SDK for the cleanest integration:

npm install shelfrun

import ShelfRun from "shelfrun";

const shelfrun = new ShelfRun({
  apiKey: "sr_live_YOUR_KEY",
});

// Scan a store
const info = await shelfrun.scan("allbirds.com");
console.log(info.platform); // "shopify"
console.log(info.product_count_estimate); // 127

// Extract products (one-liner)
const products = await shelfrun.extract("https://allbirds.com");
for (const p of products) {
  console.log(`${p.name}: $${p.price}`);
}

SDK Methods

Method	Returns	Description
scan(url)	ScanResult	Detect platform & capabilities
extract(url)	Product[]	Extract products from any URL
quickscan(url)	Product[]	Scan + extract in one call
scrape(storeId)	ScrapeResponse	Trigger full store scrape
estimateCredits(url)	CreditEstimate	Preview credit cost

Examples

Price monitoring script

#!/bin/bash
# Monitor prices daily and alert on drops
API_KEY="sr_live_YOUR_KEY"
STORE_ID="your-store-id"

products=$(curl -s "https://api.shelfrun.com/v1/stores/$STORE_ID/products" \
  -H "X-API-Key: $API_KEY")

echo "$products" | jq '.products[] | select(.price < 50) | "\(.name): $\(.price)"'

Python integration

import requests

API_KEY = "sr_live_YOUR_KEY"
headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# Quick scan
resp = requests.post(
    "https://api.shelfrun.com/v1/quickscan",
    headers=headers,
    json={"url": "allbirds.com"},
)
data = resp.json()
print(f"Found {data['products_found']} products")

for product in data["products"][:5]:
    print(f"  {product['name']}: ${product['price']}")

Error Codes

Status	Meaning	Fix
401	Invalid or missing API key	Check X-API-Key header
402	Insufficient credits	Upgrade plan
404	Store not found	Verify store_id belongs to your account
429	Rate limit exceeded	Max 60 req/min. Wait and retry.
500	Server error	Retry. If persistent, contact support.

Ready to extract data?

Get 5 free credits to try it out. No credit card required.