REST API

Complete endpoint reference for the ShopGraph extraction API.

Base URL: https://shopgraph.dev

Authentication

Three authentication methods are supported:

Method	Header	Notes
API Key	Authorization: Bearer sg_live_...	For Starter, Growth, and Enterprise tiers
Stripe MPP	X-Payment-Method: pm_...	Machine-to-machine payments for agents
Free tier	None	500 calls/month, no signup needed

Rate Limits

Tier	Monthly Limit	Rate
Free	500	10/min
Starter ($99)	10,000	60/min
Growth ($299)	50,000	200/min
Enterprise	Custom	Custom

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Endpoints

POST /api/enrich/basic

Free-tier extraction using Schema.org structured data only. No authentication required.

Request

$ curl -X POST https://shopgraph.dev/api/enrich/basic \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.allbirds.com/products/mens-tree-runners"}'

Request Body

Field	Type	Required	Description
url	string	Yes	Product page URL

Response

{
  "product": {
    "title": "Men's Tree Runners",
    "price": 98,
    "currency": "USD",
    "brand": "Allbirds",
    "availability": "InStock",
    "image": "https://cdn.allbirds.com/image/...",
    "description": "Lightweight, breathable sneakers..."
  },
  "_shopgraph": {
    "extraction_method": "schema_org",
    "confidence_score": 0.93,
    "field_confidence": { "title": 0.98, "price": 0.97 }
  },
  "cached": false,
  "free_tier": { "used": 12, "limit": 500 }
}

---

POST /api/enrich

Full extraction with LLM, hybrid merge, and Playwright fallback. Requires authentication.

Request

$ curl -X POST https://shopgraph.dev/api/enrich \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sg_live_abc123" \
  -d '{
    "url": "https://www.grainger.com/product/DAYTON-1-3-HP-4M206",
    "format": "ucp",
    "strict_confidence_threshold": 0.8,
    "include_score": true
  }'

Request Body

Field	Type	Required	Description
url	string	Yes	Product page URL
format	string	No	standard (default) or ucp
strict_confidence_threshold	number	No	Filter fields below this confidence (0-1)
include_score	boolean	No	Include AgentReady score in response
method	string	No	Force extraction method: schema_org, llm, playwright

---

POST /api/enrich/html

Extract from provided HTML. Useful when you already have the page content.

Request Body

Field	Type	Required	Description
html	string	Yes	Raw HTML content
url	string	No	Source URL for context and caching
format	string	No	standard or ucp
strict_confidence_threshold	number	No	Confidence threshold

---

POST /api/score

Score existing product data for agent readiness without extracting from a URL.

Request Body

Field	Type	Required	Description
product	ProductData	Yes	Product data object to score

Response

Returns an AgentReady Score object.

---

GET /api/stats

Get extraction statistics and test corpus results. No authentication required.

---

GET /api/health-check

Health check endpoint. Returns system status and success rates.

Error Responses

Status	Meaning
400	Invalid request (missing URL, bad format)
401	Authentication required
402	Payment required (free tier exhausted, no payment method)
429	Rate limited
500	Internal server error
504	Extraction timeout (page too slow or complex)