The API reference now documents seven endpoints that were already available:
- Taxonomy API.
GET /v1/taxonomy/categories,GET /v1/taxonomy/attributes, andGET /v1/taxonomy/attributes/{handle}/valuesreturn the categories and enrichment attributes StoreRouter assigns to products, with the search facets that select them. They are the REST equivalents of the MCPtaxonomy_treeandtaxonomy_attributetools. - Facet counts.
POST /v1/products/facet-countscounts the products a search would filter to, per category, attribute value, or color family. - Stores API.
POST /v1/stores/search,POST /v1/stores/similar, andGET /v1/stores/{domain}find stores and describe their coverage and assortment.
November 3, 2026
Brand serving now has a complete directory, lightweight profiles with article cards and navigation facets, and separate coverage snapshots. Profiles no longer contain coverage fields. Brand product browsing returns servernextOffset and supports offset 11976, equivalent to page 500 at 24 rows per page.
Python SDK 0.16.0, TypeScript SDK 0.14.0, and CLI 0.6.0 adopt these contracts. brands show reads profiles; brands coverage reads snapshots. Product results stay customer-scoped; navigation, top categories, and approximate coverage are corpus-wide metadata.
search_products now accepts the same request and returns the same successful page as POST /v1/products/search. Pass the REST body directly as MCP arguments. The tool returns requestId, items, nextCursor, and effectiveQuery directly in structuredContent, with REST product cards and image objects.The shared request supports text understanding, facet refinements, price and brand-quality bounds, catalog or store selection, ranking, and relaxation. Every successful page includes effectiveQuery, with or without debug.Keep the same arguments when continuing with nextCursor. Invalid cursors return invalid_cursor. For search failures, check isError and parse the JSON text block containing requestId, error, and message.See the MCP search reference for the current request, response, pagination, and error formats. /v1/products/search is unchanged by this release.Updates
Read back products you already hold ids for.GET /v1/products/retrieve/{uuid} returns one product and POST /v1/products/retrieve returns 1–50, in request order. Use them to refresh products you stored from search or lookup, such as product pages, carts, and saved lists.- Retrieve reads StoreRouter’s index only and never fetches from the merchant. Lookup still resolves URLs from the wild.
- An older id for a product resolves to it. The result’s
uuidis the current one; store it. - A product the merchant stopped offering is still returned, with
isActive: falseandlastDeactivatedAt. - Retrieve requests are not billed. They have their own rate-limit budget and a daily per-organization id ceiling. See Rate limits.
octogen-ai-sdk0.12.0, withretrieve_productandretrieve_products;@octogen-ai/sdk0.10.0, withretrieveProductandretrieveProducts.
Updates
You can letrelax drop your own facets. A POST /v1/products/search facet sent with "relaxable": true may be dropped by relax, in the same stages as understood filters. It still replaces an understood facet of the same name, and with relax: false it is never dropped. Every other facet you send stays sacred. Only a name a relaxation stage covers may be marked: brand profile facets, taxonomy attributes, color, color_family, and category_path.depth_2 and deeper; any other name returns a 422.This is how a caller that does its own query understanding gets the staged fallback over its own guesses: send q with understand: false, the guesses as relaxable facets, and relax: true. relax now requires q, and either understand left on or at least one relaxable facet. See facets.With debug: true, a facet you marked is reported in effectiveQuery.facets and effectiveQuery.relaxation.droppedFacets as source: "caller" with relaxable: true.Brand search without query understanding. POST /v1/brands/search takes understand (default true). understand: false matches q as written with no generated facets, filtering only by the facets you send; reference brands still apply. See Search brands.Search pages no longer overlap. Later pages of a POST /v1/products/search with q now continue page 1’s relevance ranking instead of switching to quality-score order, so a product no longer repeats across pages. A search with q still ends after a limited number of pages. Keep de-duplicating by uuid: a product can still repeat if the catalog changes between requests. Cursors from earlier pages keep working. See Pagination.SDKs. These releases declare both changes:octogen-ai-sdk0.11.0, withSearchFacetandunderstandonsearch_brands_from_text;@octogen-ai/sdk0.9.0, withSearchFacetandunderstandonsearchBrandsFromText.
Updates
More Like This takes the same controls as search.POST /v1/products/more-like-this adds relax, price_min / price_max, and brand_quality_min / brand_quality_max, with search’s semantics. facets and exclude_facets mean what they mean on search.relax defaults to true on More Like This. A short page 1 is retried with StoreRouter’s generated facets dropped in stages, never the facets or bounds you send.- A
urloruuidsource relaxes a first page with fewer thanmin(5, limit)results and nonextCursor. - An image source relaxes only an empty page.
relax: false as its default. The rule is the same on both routes: what you send is never silently dropped, but the server may drop its own inferences. See Relaxation.With debug: true, effectiveQuery.relaxation reports what relaxation did in search’s shape. It replaces relaxationRounds, relaxationDroppedFacets, and relaxationDeclinedRounds.Breaking change: include_facets is renamed to facets. A request that sends include_facets gets a 422 whose message names facets.SDKs and CLI. These releases send facets and relax:octogen-ai-sdk0.8.0;@octogen-ai/sdk0.6.0;@storerouter/cli0.4.0, whosesimilar --facetsendsfacetsand adds--no-relax.
include_facets. Upgrade them.Updates
One control per intent on product search.POST /v1/products/search now gives each field one job. q says what to find and is understood by default: StoreRouter rewrites it for retrieval and derives category, gender, color, brand, price, and attribute filters from it. facets, exclude_facets, and the bounds say what to keep, and catalogs says where to look. A request that combines fields in a contradictory way, or sends an unknown field, now returns a 422 instead of being resolved silently.New request fields:understand: falsematchesqas written and filters only by what you send.exclude_facetsremoves products that match any listed value.omit_generated_facetsdrops an understood facet that is wrong when you have no value of your own for it. A facet you send infacetsalready replaces the understood facet of the same name.brand_quality_minandbrand_quality_maxbound brand quality from 1 (very poor) to 6 (exceptional).similar_to_brandsranks results toward the style of 1 to 10 brands without filtering.
relax and debug are now documented. relax: true drops understood filters in stages when an understood q returns nothing; facets you send are never dropped. debug: true adds effectiveQuery, the search that actually ran, with each facet tagged source: "caller" or "generated". It is a report, not a request fragment to send back.Breaking changes:catalog,text_search_query, anddiversitynow return a422whose message names the replacement. Sendcatalogs: ["<key>"]instead ofcatalog. Sendqwithunderstand: false, and put filters infacetsandexclude_facets, instead oftext_search_query. Omitdiversity; it was never applied.- Each facet has one public spelling. Send taxonomy attribute handles by their bare name, such as
fit:attribute_facets.fitnow returns a422. The attribute namedcoloris the one exception and staysattribute_facets.color. A facet name may appear only once infacetsorexclude_facets. - Cursors are strict. Pass back exactly the
nextCursorthe previous page returned, with the same request body. An unusable cursor returns400withdetail: "invalid cursor"; restart from page 1 withoutcursor.
octogen-ai-sdk) and TypeScript (@octogen-ai/sdk) SDKs match the new contract. search_products and searchProducts accept the new fields and return ProgrammaticProductSearchPage, which adds requestId and a typed effectiveQuery. The SDKs check the contradictions the API would refuse before sending a request. catalog and text_search_query / textSearchQuery, deprecated in 0.4.0, are removed.The MCP search_products tool and More Like This are unchanged. See the Search Products reference, the Catalog search guide, and the Python and TypeScript SDK references for migration examples.Updates
Connect through StoreRouter domains. API examples usehttps://api.storerouter.ai/v1. The published OpenAPI contract is available at https://cdn.storerouter.ai/openapi/platform/v1/openapi.json.SDK and CLI examples set the service URLs explicitly so they work with package releases that predate the migration. Package names, API key variables, and catalog grants stay the same.Examples in earlier changelog entries below also use the current service URLs.New features
See exactly which of your URLs are covered. Every URL List’s BigQuery dataset now carries a second view,url_coverage_v1 — one row per URL in your list with (url, normalized_url, covered, exported_at) — so the uncovered portion of a list is a single query: SELECT url FROM url_coverage_v1 WHERE NOT covered.The view appears automatically in your linked dataset, including subscriptions created before it existed, and refreshes with the same daily export as products_current_v1, so the two views always describe the same snapshot. covered = TRUE means the products view has at least one row for that URL; matching tolerates the same variants as adds (query parameters, Shopify collection paths).No API or SDK changes. See the Coverage URL Lists guide.New features
Track Octogen’s coverage of your own product URL lists. The new Coverage API (/v1/coverage/url-lists) lets a Developer organization upload named sets of product URLs — up to 5 lists of 100,000 URLs each — that Octogen joins against every active crawled catalog daily. Each list is published as its own BigQuery Analytics Hub listing, and access is granted automatically to your organization’s registered BigQuery Readers, so subscribing works exactly like catalog listings. The shared view products_current_v1 holds the currently matched products with the same columns as catalog exports.URL mutations are idempotent set operations with per-URL outcomes: every URL is normalized server-side, unparseable entries are rejected individually with invalid_url without failing the batch, and matching tolerates common variants such as query-parameter differences and Shopify collection-path aliases.The Python and TypeScript SDKs expose all eight endpoints. See the Coverage URL Lists guide and API reference.Updates
Product Lookup responses now name each URL for what it is.POST /v1/products/lookup returns four URL fields with one meaning each: requestedUrl echoes the URL you submitted on every successful result; normalizedUrl (new) is the matched product’s Octogen-normalized stable URL on indexed results — submit it on a follow-up lookup to deterministically re-resolve the same product; resolvedUrl is the post-redirect URL on on-demand results; and canonicalUrl is reserved for the canonical URL the product page itself declares, on on-demand results only.Breaking change: canonicalUrl is now null on indexed results. If you stored it as the stable re-lookup URL, read normalizedUrl instead — it carries the same value indexed results previously exposed there.MCP: the lookup_product tool’s input parameter is renamed canonical_url → product_url; it accepts any real product page URL. Agents reading the tool schema at session start pick this up automatically; update any scripted caller that hardcodes the argument name.The Python and TypeScript SDKs expose the new normalizedUrl field. See the Product Lookup guide and API reference.New features
Resolve product URLs beyond Octogen’s index. Product Lookup now checks the product index first and can fall back to bounded on-demand product resolution. Every success identifiessource: "indexed" | "on_demand"; on-demand results use the same partial-safe product view without fabricating a catalog, UUID, or lifecycle state.Use resolutionMode to keep the default auto behavior, require index_only, or request on_demand_only. Use onDemandCachePolicy to prefer a recent result or request a refresh. The Python and TypeScript SDKs expose the same optional controls.See the Product Lookup guide and API reference.Updates
Developers can search and browse every active crawled catalog. This policy automatically includes catalogs activated later and always excludes merchant catalogs. Catalog-specific BigQuery listing access remains separately managed by Octogen.Omit the optionalcatalog field to search all active crawled catalogs, or pass a known active crawled catalog key to scope a request.New features
Find products similar to a source product.POST /v1/products/more-like-this accepts a product URL or UUID, derives a similarity query from Octogen product enrichment, excludes the source product, and returns the same paginated product list shape as search. Use it for related-product rails, substitutions, recommendations, and agent workflows that start from a known item.The TypeScript SDK exposes moreLikeThisProducts(...), and the Python SDK exposes more_like_this_products(...). See the More Like This guide and API reference.New features
Subscribe to catalogs in BigQuery. When Octogen shares catalogs over BigQuery Analytics Hub, the Python SDK can create linked datasets in your own Google Cloud project — so you can query full catalogs with SQL for bulk and analytical workloads. Thebigquery extra adds the subscribe_to_listing helper, an octogen-bq-subscribe CLI for one listing, and an octogen-bq-autosubscribe CLI for scheduled MCP-backed syncs as new listings become ready.New features
Developer MCP server is live. Connect any MCP-compatible AI agent — Claude Code, Claude Desktop, Codex CLI, and others — directly to your granted Octogen catalogs over OAuth 2.1 + PKCE. The initial product tools mirror the REST API:lookup_product and search_products. Tokens are scoped to your organization and refresh automatically until your sign-in session expires.See the MCP overview to choose a client and get started.Platform Catalog API v1 (REST) is generally available. Backends and batch jobs can now hit the same catalog data over HTTPS with an octo_live_... API key. Endpoints include POST /v1/products/search and POST /v1/products/lookup, with cursor-based pagination and facet support.See the API reference overview for endpoint details and the authentication guide for key setup.