Extract product data

Use the Product API to turn public product-page evidence into a normalized record. A non-product page is a valid result, and individual product fields can be missing.

Extract one product page

export CONTEXT_DEV_API_KEY="ctxt_secret_..."

curl https://api.context.dev/v1/brand/ai/product \
  --request POST \
  --header "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/products/example-item"
  }'

import ContextDev from "context.dev";

const client = new ContextDev({
  apiKey: process.env.CONTEXT_DEV_API_KEY,
});

const result = await client.ai.extractProduct({
  url: "https://example.com/products/example-item",
});

if (result.is_product_page && result.product) {
  console.log(result.product.name, result.product.price);
} else {
  console.log("The URL was not identified as a product-detail page.");
}

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

result = client.ai.extract_product(
    url="https://example.com/products/example-item",
)

if result.is_product_page and result.product:
    print(result.product.name, result.product.price)
else:
    print("The URL was not identified as a product-detail page.")

require "cgi/core"
require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

result = client.ai.extract_product(url: "https://example.com/products/example-item")

if result.is_product_page && result.product
  puts "#{result.product.name}: #{result.product.price}"
else
  puts "The URL was not identified as a product-detail page."
end

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk/v2"
    "github.com/context-dot-dev/context-go-sdk/v2/option"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    result, err := client.AI.ExtractProduct(context.Background(), contextdev.AIExtractProductParams{
        URL: "https://example.com/products/example-item",
    })
    if err != nil {
        panic(err)
    }

    if result.IsProductPage && result.JSON.Product.Valid() {
        fmt.Println(result.Product.Name, result.Product.Price)
    } else {
        fmt.Println("The URL was not identified as a product-detail page.")
    }
}

<?php

require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$result = $client->ai->extractProduct(
    url: 'https://example.com/products/example-item',
);

if ($result->isProductPage && $result->product !== null) {
    echo $result->product->name, ': ', $result->product->price, PHP_EOL;
} else {
    echo 'The URL was not identified as a product-detail page.', PHP_EOL;
}

The endpoint costs 10 credits.

Check page detection

Check both is_product_page and product before reading fields:

type ProductPageResult =
  | { kind: "product"; product: Product }
  | { kind: "not_product" }
  | { kind: "request_error"; retryable: boolean };

A category page, homepage, article, or other non-product URL can return 200 with is_product_page: false and product: null. That is different from an invalid request or an inaccessible target. The optional platform value is amazon, tiktok_shop, etsy, generic, or null. It describes the detected page platform; it is not a guarantee that every page on that platform can be extracted.

Read product fields

The product object can include:

identity: name, description, url, sku, and category;
commercial data: price, regular_price, currency, billing_frequency, and pricing_model;
availability: availability and free-form dimensions statements;
merchandising: features, target_audience, tags, image_url, and up to seven images.

price, regular_price, currency, availability, billing fields, URL, category, and images can be absent or null. Preserve that uncertainty:

Do not convert a missing price to zero.
Do not interpret a missing availability as in stock.
Keep the source URL and extraction time with the record.
Verify current price and inventory at purchase time.
Treat descriptions and features as page-derived content, not independently verified claims.

See the single-product API reference for exact enums and required response fields.

Discover products from a site

The beta multi-product endpoint extracts up to 12 products from either a domain or one direct starting URL:

curl https://api.context.dev/v1/brand/ai/products \
  --request POST \
  --header "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "domain": "example.com",
    "maxProducts": 8
  }'

const result = await client.ai.extractProducts({
  domain: "example.com",
  maxProducts: 8,
});

for (const product of result.products ?? []) {
  console.log(product.name, product.url);
}

result = client.ai.extract_products(domain="example.com", max_products=8)

for product in result.products or []:
    print(product.name, product.url)

require "cgi/core"
require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

result = client.ai.extract_products(
  body: ContextDev::Models::AIExtractProductsParams::Body::ByDomain.new(
    domain: "example.com",
    max_products: 8,
  )
)

(result.products || []).each do |product|
  puts "#{product.name}: #{product.url}"
end

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk/v2"
    "github.com/context-dot-dev/context-go-sdk/v2/option"
    "github.com/context-dot-dev/context-go-sdk/v2/packages/param"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    result, err := client.AI.ExtractProducts(context.Background(), contextdev.AIExtractProductsParams{
        OfByDomain: &contextdev.AIExtractProductsParamsBodyByDomain{
            Domain: "example.com",
            MaxProducts: param.NewOpt[int64](8),
        },
    })
    if err != nil {
        panic(err)
    }

    for _, product := range result.Products {
        fmt.Println(product.Name, product.URL)
    }
}

<?php

require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

// Use the SDK's request method: the 2.14.0 helper requires both target types.
$raw = $client->request(
    method: 'post',
    path: 'brand/ai/products',
    body: ['domain' => 'example.com', 'maxProducts' => 8],
);

$result = json_decode((string) $raw->getBody(), true, flags: JSON_THROW_ON_ERROR);
foreach ($result['products'] ?? [] as $product) {
    echo $product['name'], ': ', $product['url'] ?? '', PHP_EOL;
}

Pass exactly one of domain and directUrl. maxProducts accepts 1 to 12. This endpoint returns a discovered sample bounded by maxProducts; do not describe it as a complete catalog unless you independently reconcile it against the site’s catalog or sitemap. For larger catalogs, discover candidate URLs with the Sitemap API, filter likely product-detail pages, and extract each page. Sitemap coverage depends on what the site publishes, so reconcile the results against a known catalog when completeness matters.

Control freshness and latency

Both Product endpoints cache matching requests for seven days by default. Set:

maxAgeMs: 0 for a fresh extraction; the selected cache age is passed through to the underlying page scrapes;
a value up to 30 days when reuse matters more than freshness;
timeoutOpts.milliseconds to bound the request, up to five minutes. Use behavior: "return-partial" to accept a product after core extraction when remaining work, such as image processing, has not finished. Preserve the response’s partial: true marker; see timeouts.

Use the returned cache_metadata to record actual cache behavior. If price or availability is consequential, a fresh extraction is still not a transactional inventory guarantee.

Handle errors

Status or code	Response
`INPUT_VALIDATION_ERROR`	Correct the URL or request shape; do not retry unchanged.
`WEBSITE_ACCESS_ERROR`	The target could not be read; surface an inaccessible state or retry later.
`401` or `403`	Fix authentication, permissions, or account capacity.
`408`	Retry only if a larger latency budget is acceptable.
`429`	Honor `Retry-After` and reduce concurrency.
`5xx`	Retry with bounded exponential backoff and jitter.

Do not turn these request failures into is_product_page: false; they carry different operational meaning.

Production checklist

The input is an allowed public URL.
Non-product, partial-product, and request-error states are distinct.
Price, currency, and availability remain nullable.
Source URL, cache status, and extraction time are retained.
Multi-product output is not presented as exhaustive without reconciliation.
Product copy and images are used only with appropriate rights.

Next steps

Discover website URLs

Find candidate product pages in a site’s public sitemaps.

Scrape websites in batches

Collect raw page content with asynchronous scraping.

Product API reference

Review the product extraction request and response contract.

For the multi-product catalog API, explicit deadlines now fail with an unbilled 408 unless timeoutOpts.behavior is "return-partial". This also applies to legacy timeoutMS. Read the catalog migration note before depending on partial catalogs.

Get started

Web data

Brand data

Automation

Account and billing

Production

Extract one product page

Check page detection

Read product fields

Discover products from a site

Control freshness and latency

Handle errors

Production checklist

Next steps

Discover website URLs

Scrape websites in batches

Product API reference

​Extract one product page

​Check page detection

​Read product fields

​Discover products from a site

​Control freshness and latency

​Handle errors

​Production checklist

​Next steps

Discover website URLs

Scrape websites in batches

Product API reference

Extract one product page

Check page detection

Read product fields

Discover products from a site

Control freshness and latency

Handle errors

Production checklist

Next steps