Parse Endpoint

Overview

POST https://api.productparse.dev/v1/parse
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Accepts a product URL and returns structured JSON. The response schema is consistent regardless of which extraction method was used.

Minimal request

{
  "url": "https://www.example.com/products/widget-pro"
}

Full request

{
  "url": "https://www.example.com/products/widget-pro",
  "extractionHint": "Include all colour and size variants separately. Return shipping lead time.",
  "includeScreenshot": true,
  "forceRefresh": false,
  "strategies": ["jsonld", "cached-script", "adaptive"]
}

Minimal response

{
  "title": "Widget Pro",
  "brand": "Acme Corp",
  "price": {
    "amount": 129.99,
    "currency": "USD"
  },
  "availability": "in_stock",
  "images": ["https://example.com/images/widget-pro.jpg"],
  "source": {
    "type": "jsonld",
    "method": "fast-path",
    "confidence": 0.97
  }
}

Full response

{
  "title": "Widget Pro – Titanium Edition",
  "brand": "Acme Corp",
  "sku": "WP-TI-001",
  "description": "The most durable widget we've ever built...",
  "price": {
    "amount": 129.99,
    "currency": "USD"
  },
  "availability": "in_stock",
  "images": [
    "https://example.com/images/widget-pro-1.jpg",
    "https://example.com/images/widget-pro-2.jpg"
  ],
  "variants": [
    { "colour": "Titanium Silver", "size": "M" },
    { "colour": "Midnight Black", "size": "M" },
    { "colour": "Midnight Black", "size": "L" }
  ],
  "shipping": {
    "summary": "Free shipping over $75",
    "eta": "3–5 business days"
  },
  "quantityBreaks": [
    { "minQuantity": 1, "maxQuantity": 9, "unitPrice": 129.99 },
    { "minQuantity": 10, "maxQuantity": 49, "unitPrice": 114.99 },
    { "minQuantity": 50, "maxQuantity": null, "unitPrice": 99.99 }
  ],
  "source": {
    "type": "adaptive",
    "method": "cached-script",
    "confidence": 0.94
  },
  "artifacts": {
    "screenshotUrl": "https://cdn.productparse.dev/s/abc123.png",
    "screenshotToken": "abc123"
  },
  "meta": {
    "extractionTime": 312,
    "requestId": "req_01j8x..."
  }
}

Batch mode

Send an array of URLs to process up to 20 URLs in parallel:

{
  "urls": [
    "https://example.com/products/widget-a",
    "https://example.com/products/widget-b",
    "https://example.com/products/widget-c"
  ]
}

Batch response:

{
  "batch": true,
  "results": [
    {
      "url": "https://example.com/products/widget-a",
      "success": true,
      "title": "Widget A",
      "price": { "amount": 49.99, "currency": "USD" },
      ...
    },
    {
      "url": "https://example.com/products/widget-b",
      "success": false,
      "error": "Page returned 404"
    }
  ],
  "meta": {
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "extractionTime": 1840
  }
}

HTTP status codes