Quickstart.

1. Get a key

Sign in, create a key from the dashboard, copy the secret once (you won't see it again).

2. Make your first call

POST the product URL to /v1/extract with your key in the x-api-key header.

curl https://api.cartpie.com/v1/extract \
  -H "x-api-key: $CARTPIE_KEY" \
  -H "content-type: application/json" \
  -d '{ "url": "https://www.ikea.com/gb/en/p/billy-bookcase-white-00263850/" }'

3. Read the response

Every successful response has data (the product) and meta (billable, cached, timing).

{
  "data": {
    "title": "BILLY Bookcase, white",
    "price": "55.00",
    "currency": "GBP",
    "availability": "inStock"
  },
  "meta": { "billable": true, "cached": false, "duration_ms": 412 }
}

Authentication

Two planes: /v1/* uses an x-api-key header; /manage/* (the dashboard) uses a Supabase bearer token. Keys come in two environments — cp_live_… and cp_test_….

Format & fields

Choose product (default), markdown, or both. Optionally project specific fields and set a cache freshness window.

// product only (default — smallest, cheapest)
POST /v1/extract  { "url": "…", "format": "product" }

// markdown of the page (for LLM context)
POST /v1/extract  { "url": "…", "format": "markdown" }

// both, in one call
POST /v1/extract  { "url": "…", "format": "both" }

POST /v1/extract
{
  "url": "https://…",
  "fields": ["title", "price", "currency", "availability", "identifiers.gtin"],
  "freshness": "6h"
}

Errors

All errors share the same envelope: { "error": { "code", "message" } }. Common codes:

MCP server

Run npx @cartpie/mcp to expose extract_product, extract_products, and find_offers to any MCP client (Claude, Cursor, etc.). Coming soon.