On this page

For Developers

Integrate ProductIndex into your app or AI agent — your users get AI product search across 885+ synthesized profiles in 31 categories. Your agent gets real-time pricing via the RFQ marketplace: consumer agents can negotiate prices with verified producers on behalf of your users. Integration surfaces: 6 MCP tools, per-product endpoints in HTML / Markdown / JSON-LD, and an A2A-compatible agent card. Free tier available; OAuth 2.1 handles sign-in — clients like Grok and Claude Desktop manage it automatically.

Quick Reference

MCP endpoint POST https://mcp.productindex.ai/mcp/
Protocol MCP — legacy (through 2025-11-25) and 2026-07-28, served automatically per request · Streamable HTTP
Auth header Authorization: Bearer <access_token>
Scope mcp
Rate limit 500 requests / day per authenticated user
Authorize URL https://productindex.ai/oauth/authorize/
Token URL POST https://productindex.ai/api/oauth/token/
Client registration CIMD (preferred) or DCR at POST https://productindex.ai/api/oauth/register/
OAuth server metadata /.well-known/oauth-authorization-server.json
MCP descriptor /.well-known/mcp.json
Tools 31 total — 12 consumer, 19 producer (catalog, pricing, team, enrichment). Full list: /docs/mcp
CIMD supported Yes — client_id_metadata_document_supported: true in server metadata

MCP Server

31 tools over Streamable HTTP — the server serves both the legacy protocol family (through MCP 2025-11-25) and 2026-07-28 automatically per request, depending on how your client shapes its handshake. All requests are POST to https://mcp.productindex.ai/mcp/ with a JSON-RPC 2.0 body. OAuth 2.1 Bearer token required on every request.

Endpoint POST https://mcp.productindex.ai/mcp/
Protocol MCP — legacy (through 2025-11-25) and 2026-07-28, served automatically · Streamable HTTP (POST only)
Auth Authorization: Bearer <access_token> — OAuth 2.1 required
Descriptor /.well-known/mcp.json

Core Search Tools

The 6 consumer search tools below cover the common case. ProductIndex has 31 tools total (12 consumer — including saved-product management and the bundle-aware product_curator — plus 19 producer tools for catalog, pricing, team, and enrichment management); see the complete Consumer/Producer breakdown at /docs/mcp.

Tool Description
list_categories All 31 categories with product counts. No parameters.
list_category_products Paginated product list for a category. Params: category (required), limit, offset, sort, on_sale, include_discontinued.
get_product Full product profile by slug. Params: category, slug (both required), sections (string array — subset retrieval).
search_products Semantic search via pgvector + Cohere reranking with keyword fallback. Params: query (required), category, min_price, max_price, sort, on_sale, include_discontinued, limit.
find_similar Nearest-neighbour similarity to a known product. Params: category, slug (both required), max_price, limit.
find_retailers Merchants carrying a product — triggers RFQ fanout and returns ranked offers with affiliate-attributed buy links. Params: query (required), product_slug, max_results.

Request / Response Example

Every call is a POST to the same endpoint. Send initialize first, then any tool call.

// 1. Initialize
POST https://mcp.productindex.ai/mcp/
Authorization: Bearer <access_token>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0"}}}

// 200 OK
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{}},"serverInfo":{"name":"ProductIndex","version":"1.0.0"}}}

// 2. Tool call
POST https://mcp.productindex.ai/mcp/
Authorization: Bearer <access_token>
Content-Type: application/json

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_products","arguments":{"query":"espresso machine under $500","limit":5}}}

// 200 OK
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"..."}]}}

Full setup instructions for Grok, Claude Desktop, Cursor, and Windsurf: MCP Server documentation →

Multi-format content endpoints

Every product and category is available in machine-readable formats for direct RAG ingestion, structured data pipelines, and LLM agents that prefer URL-based retrieval over the MCP server. No authentication required.

Format URL pattern Use case
HTML — product /p/{category}/{slug} Human-readable product page
Markdown — product /p/{category}/{slug}.md LLM-friendly; verdict, review themes, specs, images, where-to-buy. noindex.
JSON-LD — product /p/{category}/{slug}.json Schema.org Product object. noindex.
HTML — category /c/{category} Human-readable category listing with all products
Markdown — category /c/{category}.md Full dump of every product profile in the category as a single document — suitable for bulk RAG ingestion. noindex.

Agent Card (A2A)

ProductIndex publishes a Google Agent-to-Agent (A2A) compatible agent card describing its skills and capabilities in machine-readable JSON. Read automatically by A2A-compatible orchestrators.

Card URL /.well-known/agent.json
Skills Product recommendation · Product lookup · Category browse · Product offers · Request for Quote · What changed
Registry Pending — Google A2A registry and Linux Foundation AI Agent Registry

RFQ Integration — Level 2 Producer Agents

If you operate a retailer or manufacturer and want to receive live Request-for-Quote (RFQ) calls from consumer agents via ProductIndex, register your agent endpoint in the Producer Dashboard → Settings → Agent Integration. ProductIndex will fan out to your endpoint when a consumer agent submits an RFQ for a product you carry.

RFQ Request — What Your Agent Receives

ProductIndex calls your registered offer endpoint with a JSON-RPC 2.0 POST request:

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": "<rfq_session_uuid>",
  "params": {
    "message": {
      "messageId": "<uuid>",
      "role": "user",
      "parts": [{ "kind": "text", "text": "Request for quote: coffee-grinders/baratza-encore-esp, qty 1, ship to US-CA-941" }],
      "metadata": {
        "skill": "respond-to-rfq",
        "rfq_id": "<rfq_session_uuid>",
        "product_slug": "coffee-grinders/baratza-encore-esp",
        "quantity": 1,
        "delivery_region": "US-CA-941",
        "deadline_iso": "2026-06-01",
        "requestor": "https://productindex.ai/.well-known/agent.json"
      }
    }
  }
}
Field Type Description
metadata.product_slug string Canonical ProductIndex slug for the requested product
metadata.quantity integer Units requested (default 1)
metadata.delivery_region string Coarse delivery region: ISO 3166 country or country-subdivision, optionally plus a postal prefix (e.g. US, US-CA, US-CA-941). Usually the first 3 postal characters; the full postal code only when the buyer chose to share it. Omitted (null) when unknown. Buyer identity, contact details and budget are never sent
metadata.deadline_iso date (YYYY-MM-DD) Latest acceptable delivery date (optional)

RFQ Response — What You Must Return

Respond with a JSON object (not JSON-RPC envelope — bare object only) within 25 seconds. ProductIndex fans out RFQs to registered agent endpoints asynchronously — the consumer's agent gets an immediate task handle and doesn't block on your response time, so you have more room to work than a synchronous request-response cycle would suggest:

{
  "price_usd": 169.99,
  "list_price_usd": 189.99,
  "in_stock": true,
  "estimated_shipping_days": 3,
  "shipping_cost_usd": 0,
  "offer_id": "<uuid>",
  "offer_expires_at": "2026-06-01T12:00:00Z",
  "claim_url": "https://yourstore.com/cart?offer=<uuid>",
  "terms": "Free returns within 30 days"
}
Field Required Description
price_usd Yes Your offered price in USD, per unit (not the total for quantity)
in_stock Yes Boolean — false causes your offer to be deprioritized
claim_url Yes URL consumer agent can redirect to for purchase. Must be https://.
offer_expires_at Yes ISO 8601 — when the quoted price expires. Max 24 hours from now.
shipping_cost_usd No Shipping cost (0 for free shipping). Omit if unknown — you will rank lower.
list_price_usd No Original MSRP if your offer is discounted
estimated_shipping_days No Business days to deliver. Omit if unknown.
terms No Short return/warranty/conditions string shown to consumer

Offers are ranked by total cost (price_usd + shipping_cost_usd). Out-of-stock offers are demoted regardless of price. Responses that arrive after 25 seconds are dropped.

Authentication

Every RFQ call from ProductIndex carries authentication headers so your server can verify the request is genuine. Choose a scheme, generate your own secret, and register it in the Producer Dashboard → Settings → Agent Integration. ProductIndex encrypts and stores the secret — it is never returned after registration.

Scheme You generate Headers sent by ProductIndex How to verify
Bearer token Any secret string ≥ 16 chars (use a random token) Authorization: Bearer <your-token> Compare header value against your stored token with a constant-time comparison
HMAC-SHA256 A random signing secret ≥ 16 chars (32+ bytes of entropy recommended) X-ProductIndex-Signature: <hex>
X-ProductIndex-Timestamp: <unix_seconds>
Recompute HMAC and compare — see spec below

Generating a secret

// Node.js — generate a cryptographically random secret
import { randomBytes } from "crypto";
const secret = randomBytes(32).toString("hex"); // 64-char hex string
console.log(secret); // paste this into the dashboard

Go to Producer Dashboard → Settings → Agent Integration, select your auth type, paste your secret, and save. ProductIndex will use it to sign all outbound RFQ calls to your endpoint from that point forward.

HMAC Verification

Signature is HMAC-SHA256(secret, "${timestamp}.${rawBodyString}") — the Unix timestamp in seconds, a literal period, then the raw request body string exactly as received. Reject requests where |now - timestamp| > 300 seconds (5-minute replay window).

// Node.js verification example
import { createHmac, timingSafeEqual } from "crypto";

function verifyProductIndexRequest(secret, req) {
  const timestamp = parseInt(req.headers["x-productindex-timestamp"], 10);
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${req.rawBody}`)
    .digest("hex");
  // Use timingSafeEqual to prevent timing attacks
  return timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-productindex-signature"]));
}

Agent Card Requirement

Your agent card (at /.well-known/agent.json on your verified domain) must declare the respond-to-rfq skill. Minimum declaration:

{
  "skills": [{
    "id": "respond-to-rfq",
    "description": "Responds to price quote requests with current pricing, availability, and shipping terms"
  }]
}

ProductIndex fetches and validates this card when you register your agent card URL. The card must be on the same domain as your verified producer organization.

ProductIndex derives your RFQ endpoint from your agent card URL by taking the domain root and appending /message:send. If your card is at https://mystore.com/.well-known/agent.json, ProductIndex will POST RFQ requests to https://mystore.com/message:send. Your server must expose a POST /message:send route at the domain root.

Timeout and Error Handling

Return HTTP 200 with a valid JSON response body within 25 seconds. If you cannot fulfill the RFQ (out of stock, product not carried), return HTTP 200 with {"in_stock": false, "price_usd": 0, "claim_url": "", "offer_expires_at": ""} rather than a non-200 status. Repeated timeouts or errors degrade your integration status and reduce your ranking priority.

Your endpoint is called from an async continuation, not the consumer agent's original request — ProductIndex acknowledges the RFQ immediately with an A2A Task handle (status.state: "submitted"), fans out to every registered producer for that product concurrently, and the consumer agent polls tasks/get until the task reaches completed. Your 25-second window is bounded by ProductIndex's own Lambda execution limit, not by how long a human shopper is willing to wait on a page load.

Report sales from your store

For producers whose store isn't on Shopify (the Shopify app reports sales for you). Your server tells ProductIndex when an order came from a ProductIndex link, and when such an order is refunded or cancelled. Requests are signed with your own Ed25519 key; ProductIndex only ever holds the public half.

1. Create a signing key

In Producer Dashboard → Sales reporting (organization owners and admins), generate a key in your browser or paste a public key you made yourself. The dashboard shows your key id (custom_…) and your store value (your organization id). To make the key yourself:

openssl genpkey -algorithm ed25519 -out productindex-key.pem   # private: keep on your server
openssl pkey -in productindex-key.pem -pubout                   # public: paste into the dashboard

You can have up to 3 active keys, so you can rotate: add the new key, deploy it, then revoke the old one. A revoked key stops working immediately.

2. Keep pi_ref with the order

Every link from ProductIndex to your store arrives with ?pi_ref=<click id> (a UUID). It identifies the click, not the shopper. When a visitor lands with it:

  • Store it first-party: a cookie on your own domain or your server-side session. Keep it for 30 days; a newer pi_ref replaces an older one.
  • Attach it to the order at checkout (an order attribute, note or metadata field).
  • When the order is placed or paid, post a conversion (below). Orders more than 30 days after the click aren't attributed.

3. Post a conversion

POST https://productindex.ai/api/attribution/conversion/?store=<your org id>, signed (step 5):

{
  "pi_ref": "6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b",
  "order_id": "1001",
  "ordered_at": "2026-11-03T15:04:05Z",
  "subtotal": "80.00",
  "currency": "USD"
}
pi_refThe click id you stored.
order_idYour order id, 1–255 characters. One conversion per order.
ordered_atOptional ISO 8601 time with a zone; not in the future. Defaults to now.
subtotal A decimal string with at most 2 places. The commission base defined in the Producer Terms (§1.8): the merchandise subtotal after discounts, excluding tax, shipping, tips and gift cards.
currencyISO 4217 code. Every currency is recorded; only USD orders currently accrue commission.

Responses:

  • 200 {"recorded": true, "pi_ref", "event"}. Re-sending the same order_id and pi_ref returns the already-recorded event with "replay": true, so retries are safe. A re-send never changes it: correct an order with an adjustment (step 4).
  • 400 a field is invalid (the error message says which).
  • 404 the click isn't one of your links. 410 the order is outside the 30-day window.
  • 409 the click or order is already used with a different order or click. It can also mean two copies of the same request arrived at once; re-send it once and a 200 with "replay": true confirms it was recorded.

4. Post refunds and cancellations

POST https://productindex.ai/api/attribution/adjustment/?store=<your org id>, signed:

{
  "order_id": "1001",
  "refund_id": "re_123",
  "kind": "refund",
  "amount": "20.00",
  "currency": "USD",
  "occurred_at": "2026-11-10T09:00:00Z"
}
  • kind is "refund" (amount required: the refunded part of the subtotal) or "cancel" (without amount, reverses whatever is left).
  • refund_id is your id for this refund; re-sending it is a no-op replay.
  • currency must match the order's.
  • Adjustments count within 60 days of the order. Later ones return 200 {"applied": false, "reason": "outside_window"}.
  • 404 there's no conversion for that order_id. 409 a duplicate of the same request arrived at the same time; re-send it to get the recorded result.

5. Sign each request

ProductIndex's profile of RFC 9421 HTTP Message Signatures with Ed25519. Three headers:

Content-Digest:  sha-256=:<base64 SHA-256 of the exact body bytes>:
Signature-Input: pi=("@method" "@authority" "@path" "@query" "content-digest");created=<unix>;expires=<unix>;nonce="<22 base64url chars>";keyid="<your custom_ key id>";alg="ed25519";tag="productindex-integration"
Signature:       pi=:<base64 Ed25519 signature of the signature base>:

The signature base is these six lines joined with \n (no trailing newline):

"@method": POST
"@authority": productindex.ai
"@path": /api/attribution/conversion
"@query": ?store=<your org id>
"content-digest": sha-256=:…:
"@signature-params": ("@method" "@authority" "@path" "@query" "content-digest");created=…;expires=…;nonce="…";keyid="…";alg="ed25519";tag="productindex-integration"
  • Parameters must appear exactly in this order. @path has no trailing slash; @query keeps its leading ?.
  • expires is at most 60 seconds after created, and created may be at most 30 seconds ahead of our clock. Sign just before sending.
  • Use a new random nonce for every request, including retries. A reused nonce is refused as a replay.
  • ?store= must be your own organization id. A merchant key can only call these two endpoints.
  • Auth errors: 401 bad, expired or replayed signature, or an unknown or revoked key. 403 wrong store or endpoint for this key. 404 organization not active. 503 temporarily unable to check replays: retry with a new signature.

Node reference implementation

Node 18+, no dependencies. This is the exact file our test suite signs with and verifies against the production verifier; save it as productindex-sign.mjs. Retry network errors and 5xx responses with backoff; each call signs afresh.

// ProductIndex sales reporting: sign and send a conversion or adjustment.
// Node 18+, no dependencies. Shown verbatim on /docs/developers#dev-sales-reporting.
// keyId: your key's id (custom_…); privateKeyPem: its PEM private key; orgId: your "store" value.
import { createHash, createPrivateKey, randomBytes, sign } from "node:crypto";

export function signProductIndexRequest({ method, url, body = "", keyId, privateKeyPem }) {
  const u = new URL(url);
  const path = u.pathname.length > 1 && u.pathname.endsWith("/") ? u.pathname.slice(0, -1) : u.pathname;
  const created = Math.floor(Date.now() / 1000);
  const nonce = randomBytes(16).toString("base64url"); // 22 chars, never reused
  const digest = `sha-256=:${createHash("sha256").update(body).digest("base64")}:`;
  const params = `("@method" "@authority" "@path" "@query" "content-digest");created=${created};` +
    `expires=${created + 60};nonce="${nonce}";keyid="${keyId}";alg="ed25519";tag="productindex-integration"`;
  const base = [
    `"@method": ${method.toUpperCase()}`,
    `"@authority": ${u.host.toLowerCase()}`,
    `"@path": ${path}`,
    `"@query": ${u.search || "?"}`,
    `"content-digest": ${digest}`,
    `"@signature-params": ${params}`,
  ].join("\n");
  const signature = sign(null, Buffer.from(base), createPrivateKey(privateKeyPem)).toString("base64");
  return {
    "Content-Type": "application/json",
    "Content-Digest": digest,
    "Signature-Input": `pi=${params}`,
    Signature: `pi=:${signature}:`,
  };
}

// kind: "conversion" or "adjustment". Sign the exact bytes you send.
export async function reportToProductIndex(kind, payload, { orgId, keyId, privateKeyPem, baseUrl = "https://productindex.ai" }) {
  if (kind !== "conversion" && kind !== "adjustment") throw new Error(`unknown kind: ${kind}`);
  const url = `${baseUrl.replace(/\/+$/, "")}/api/attribution/${kind}/?store=${encodeURIComponent(orgId)}`;
  const body = JSON.stringify(payload);
  const headers = signProductIndexRequest({ method: "POST", url, body, keyId, privateKeyPem });
  const res = await fetch(url, { method: "POST", headers, body });
  return { status: res.status, body: await res.json().catch(() => null) };
}
// Example: after an order that carried pi_ref is paid
import { readFileSync } from "node:fs";
import { reportToProductIndex } from "./productindex-sign.mjs";

const auth = {
  orgId: process.env.PRODUCTINDEX_STORE,     // your store value from the dashboard
  keyId: process.env.PRODUCTINDEX_KEY_ID,    // custom_…
  privateKeyPem: readFileSync("productindex-key.pem", "utf8"),
};
const res = await reportToProductIndex("conversion", {
  pi_ref: order.piRef, order_id: String(order.id), ordered_at: order.createdAt,
  subtotal: order.merchandiseSubtotalAfterDiscounts,  // a string, e.g. "80.00"
  currency: order.currency,
}, auth);
if (res.status !== 200) console.error("ProductIndex conversion not recorded", res);

Machine-readable: both endpoints are in /openapi.json (security scheme integrationSignature).

REST API

Full request/response schemas, status codes, and validation rules for the routes below are published as an OpenAPI 3.1 spec at /openapi.json — this section covers the common cases. Producer routes (offers, org integration) require a producer account; see Producer Dashboard → Settings to create one.

Search

POST /api/search/ runs the same semantic search pipeline behind the site's own search bar — pgvector + BM25 with Cohere reranking. No authentication required.

// Request
{
  "query": "quiet coffee grinder under $200"
}

// Response — 200
{
  "query_id": "<uuid>",
  "results": [
    {
      "slug": "baratza-encore-esp",
      "title": "Baratza Encore ESP",
      "category": "coffee-grinders",
      "verdict": "The best burr grinder for espresso under $200.",
      "price_range": "$179–$199",
      "url": "/p/coffee-grinders/baratza-encore-esp",
      "similarity": 0.87,
      "is_sponsored": false
    }
  ]
}

A signed-in, email-verified caller can add "bundle": true to request a multi-category bundle plan (e.g. "full kitchen set, $900 budget") instead of a flat result list — see /openapi.json for the bundle response shape.

Offers

Producer-managed promotional offers on your claimed products. All four routes require a producer session or a signed request from the Shopify plugin.

Method & path Purpose
POST /api/offers/create/ Create a new offer (draft status) for a product you have a verified sells/manufactured_by relationship to
PATCH /api/offers/edit/ Edit an existing offer's fields (headline, price, dates, etc.)
GET /api/offers/list/ List your organization's offers plus the products you're eligible to create offers for
PATCH /api/offers/update/ Change an offer's status — active, paused, or expired

Org Agent Integration

Configure how your organization responds to RFQ requests — either a self-hosted A2A agent card (see RFQ Integration above) or ProductIndex-managed pricing rules.

Method & path Purpose
POST /api/org/register/ Create a new producer organization (signed-in session only — no bearer-token path)
POST /api/org/register-agent-card/ Register your self-hosted agent card URL for RFQ delivery. Owner/admin session role required (bearer-token callers are exempt).
GET / PATCH /api/org/agent-integration/ Read or update your Managed vs. self-hosted mode and pricing rules
POST /api/org/ucp-check/ Re-check your domain for Universal Commerce Protocol (UCP) checkout support (signed-in session only)

Versioning & deprecation

This is version 1 of the REST API. Breaking changes — removing or renaming a field, endpoint, or parameter, or changing a type or status code — never ship to version 1. Additive changes (new fields, endpoints, or optional parameters) can, so ignore fields you don't recognize. You may send ProductIndex-API-Version: 1 to pin the version; requests without it get version 1, and any other value is rejected with a 400 (unsupported_api_version).

If a version 2 is ever needed, it will be announced here at least 90 days before version 1 changes or is retired. During that window every affected version 1 response carries a Deprecation header (RFC 9745), a Sunset header (RFC 8594) with the retirement date, and a Link: <…>; rel="deprecation" header pointing at the migration notes. Errors are JSON: { "error": "…" }, plus a code and a docs link for unknown routes (404) and for a method a route doesn't support (405, with an Allow header listing the ones it does).

LLM Text Files

Static files formatted for LLM context windows and RAG pipelines, following the llms.txt convention. No authentication required.

File Contents
llms.txt MCP server reference + index of all products with one-line verdicts. Start here.
llms-full.txt Full text of every product profile — suitable for offline RAG ingestion. Large file.

Discovery Endpoints

Machine-readable discovery documents for automated use by agents and OAuth clients — mostly under the standard .well-known path, plus the OpenAPI spec at the site root. All public — no authentication required.

Path Purpose
/.well-known/mcp.json MCP descriptor — tool schemas and per-client config blocks
/.well-known/agent.json A2A agent card — skills, capabilities, and MCP extension pointer
mcp.productindex.ai/mcp/server-card (also /.well-known/mcp/server-card.json) MCP server card (SEP-2127) — name, title, description, icons, and endpoint; listed in /.well-known/ai-catalog.json
/.well-known/oauth-authorization-server.json OAuth 2.1 authorization server metadata (RFC 8414) — includes all endpoint URLs, supported grant types, CIMD support flag
/.well-known/oauth-protected-resource.json OAuth protected resource metadata (RFC 9728)
/openapi.json OpenAPI 3.1 spec for the public REST surface — search, product/category reads, offers, and producer org agent-integration endpoints

Client Authorization — CIMD

ProductIndex supports Client ID Metadata Documents (CIMD) — a stateless alternative to OAuth Dynamic Client Registration (DCR) being standardized in MCP SEP-991 and a companion IETF draft. Instead of pre-registering a client and receiving an opaque client ID, your app hosts a static JSON file at a stable HTTPS URL. That URL is the client ID — no registration step, no database entry on our side.

How it works

Host a JSON file at any stable HTTPS URL on your domain. That URL becomes your client_id. When you send an OAuth authorization request, ProductIndex fetches the document, validates that the client_id field inside it exactly matches the URL it was fetched from, then uses your redirect_uris list to verify the redirect_uri in your request.

{
  "client_id": "https://yourapp.example.com/oauth/client.json",
  "client_name": "Your App Name",
  "client_uri": "https://yourapp.example.com",
  "redirect_uris": [
    "https://yourapp.example.com/oauth/callback"
  ],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Then start the OAuth flow using that URL as client_id:

GET https://productindex.ai/oauth/authorize/
  ?client_id=https://yourapp.example.com/oauth/client.json
  &redirect_uri=https://yourapp.example.com/oauth/callback
  &response_type=code
  &code_challenge=<S256 PKCE challenge>
  &code_challenge_method=S256
  &scope=mcp
  &state=<random state>

Requirements

Requirement Detail
URL scheme https:// only — no http://, no localhost URLs
client_id self-reference The client_id field inside the JSON must exactly match the URL it was fetched from
Required fields client_id, client_name, redirect_uris (non-empty array)
Auth method token_endpoint_auth_method: "none" — public clients with PKCE only
Response size Must be under 64 KB
Fetch timeout 5 seconds — serve the file from a CDN or static host

ProductIndex caches valid CIMD documents for 5 minutes and invalid results for 1 minute. Private IP ranges, loopback addresses, and link-local addresses are blocked before fetch (SSRF protection).

Traditional DCR

If your client cannot host a static HTTPS file (e.g., a CLI tool or local app), register via Dynamic Client Registration at POST /api/oauth/register/. DCR issues an opaque UUID as the client_id. CIMD is preferred for web apps and server-side integrations.

OAuth 2.1 + PKCE Flow

Complete flow for obtaining an access token. All clients are public (token_endpoint_auth_method: none) — PKCE is the only security mechanism, no client secret is issued or required.

Step 1 — Generate PKCE pair

// Generate a cryptographically random code_verifier (43–128 URL-safe chars)
const verifier = base64url(crypto.randomBytes(32));

// Derive code_challenge
const challenge = base64url(crypto.createHash('sha256').update(verifier).digest());

Step 2 — Redirect user to authorization endpoint

GET https://productindex.ai/oauth/authorize/
  ?response_type=code
  &client_id=<your-client-id>
  &redirect_uri=<your-registered-redirect-uri>
  &code_challenge=<challenge>
  &code_challenge_method=S256
  &scope=read%20write:offers
  &state=<random-csrf-token>

scope is space-separated: read (every consumer tool and the producer read tools), plus any of write:catalog, write:offers, write:org, write:team, write:enrichment for producer write tools. scope=mcp, or no scope, still means full access. A tool call outside the token's scopes gets 403 with WWW-Authenticate: Bearer error="insufficient_scope", scope="…" listing the scopes to re-authorize with.

User signs in (or is auto-approved if they previously granted this client at least these scopes). ProductIndex redirects to your redirect_uri with ?code=<auth_code>&state=<state>.

Step 3 — Exchange code for tokens

POST https://productindex.ai/api/oauth/token/
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<auth_code_from_redirect>
&redirect_uri=<same-redirect-uri>
&client_id=<same-client-id>
&code_verifier=<verifier>

// 200 OK
{
  "access_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<refresh_token>"
}

Step 4 — Call the MCP server

POST https://mcp.productindex.ai/mcp/
Authorization: Bearer <access_token>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

Step 5 — Refresh an expired token

POST https://productindex.ai/api/oauth/token/
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=<refresh_token>
&client_id=<same-client-id>

// 200 OK — new access_token and refresh_token issued; old refresh_token revoked
Response header Value
X-RateLimit-Remaining Requests remaining today
X-RateLimit-Reset Unix timestamp when the daily quota resets

Rate limits

OAuth 2.1 with PKCE is required for all requests. AI clients like Grok and Claude Desktop handle the sign-in flow automatically — connect once and they manage token refresh.

Tier Limit How to activate
Authenticated (free) 500 requests / day OAuth 2.1 — clients like Grok and Claude Desktop handle sign-in automatically

Remaining quota and reset time are returned on every response as X-RateLimit-Remaining and X-RateLimit-Reset headers.

Questions

For integration questions or to report an issue with the API: hello@productindex.ai