# API overview

> products.ai API overview: who it's for, how to request access, the illustrative tools and a sample search_products response with products matched by barcode.

> **Preview:** The products.ai API opens by request. This page describes how it works at launch. Tool names and fields on this page are illustrative until the API docs ship.

The products.ai API gives your product the answers Pius Bot gives in chat, as data: which product fits a question, why it fits, why not the others, and which shop to buy it from. It's for businesses and builders, and access is by request.

## Who is the API for?

It's for businesses and builders who want products and offers inside their own app, for example a shopping assistant for a few countries or a planner that suggests gear. The In your product plan works through the API or MCP.

Two other routes are simpler if they fit you better. If you only want answers for yourself, [products.ai chat](https://products.ai/docs/what-is-products-ai) needs the least setup. If you want products.ai inside the AI assistant you already use, [MCP](https://products.ai/docs/mcp) is the shorter path.

## How do you get access?

You request it, and a person in Amsterdam reads every request.

1. Open the [access form](https://products.ai#access) and choose **Use the API**.
2. Add your work email, your company or project, and what you're building and where.
3. Press **Request access**. Your email app opens with a pre-filled message to api@products.ai, and nothing is sent until you press send.

You can also email api@products.ai directly. Access comes with its own agreement, separate from the consumer [Terms](https://products.ai/terms), and that agreement sets the terms for your use.

## Which tools does the API have?

Four, in the current illustrative design:

| Tool | What it returns |
| --- | --- |
| `search_products` | Products for a plain-language question |
| `get_product` | One barcode: specs, variants and alternatives |
| `compare_products` | Products side by side, by barcode |
| `get_offers` | Listed offers with price, stock and the date each was listed |

## What does a search_products response look like?

A pick with its reasons first, then where to buy it. This illustrative response answers "noise-cancelling headphones under €300 for travel":

```json
{
  "best_fit": "Sony WH-1000XM5",
  "why_it_fits": [
    "Strongest ANC for flights",
    "€73,01 under your budget"
  ],
  "why_not": [
    "Momentum 4: less quiet",
    "QC Ultra: over budget"
  ],
  "best_pick": {
    "shop": "bol.com",
    "price": 226.99,
    "why": "In stock, free delivery in 1–2 days"
  },
  "second_chance": [{
    "condition": "Refurbished, grade A",
    "price": 179.00,
    "why_not": "Asked for new"
  }]
}
```

| Field | What it means |
| --- | --- |
| `best_fit` | The product that fits the question best |
| `why_it_fits` | Short reasons, tied to what was asked |
| `why_not` | One line for each alternative that wasn't picked |
| `best_pick` | The shop to buy from: `shop`, `price` and `why` (stock and delivery) |
| `second_chance` | Offers outside the question that may still suit, each with its own `why_not` |

Show the reasons in your app, next to the pick and the shop. They tell your users why this product and why this shop, and that honesty is what makes the next pick believable.

## How are products and offers matched?

Every product is matched by its barcode, the GTIN (EAN in Europe, UPC in North America). The Sony WH-1000XM5, for example, is GTIN 4548736132580. That keeps models one digit apart, like the WH-1000XM4 and WH-1000XM5, as separate records.

Every offer carries its shop and the date the shop listed it. Prices come only from offers that shops list, and Pius Bot never writes a price itself. An old listing keeps its date, so your users can see how fresh a price is. Shops in your user's country come first. [Where to buy](https://products.ai/docs/where-to-buy) covers how Pius picks the shop.

## What is still illustrative?

The tool names, the field names and the response shape on this page are illustrative until the API docs ship. Use them to plan your integration, not to ship code against, because names can still change.

What comes with access instead: the real docs, how you connect, and what your agreement covers. Some offers carry affiliate links, flagged in the data; [Affiliate links and earning](https://products.ai/docs/affiliate-links) explains how that works and what your app must disclose.