Skip to main content
The StoreRouter Python SDK gives you an async, type-safe client for the StoreRouter commerce API. Install it from PyPI, point it at your OCTOGEN_PLATFORM_API_KEY, and you can search products by keyword and facet, find products similar to a source product, and look up any product by URL — all backed by Pydantic models so your IDE can autocomplete every field.

Installation

1

Install the package

Requires Python 3.11 or later. Install octogen-ai-sdk from PyPI. This page documents version 0.11.0.
To work on the SDK itself, clone the public octogen-dev repository and run uv sync in sdks/python.
2

Set your API key

The client reads your key from the OCTOGEN_PLATFORM_API_KEY environment variable automatically.
You can also pass api_key= directly to the constructor if you prefer to manage secrets yourself (see Authentication below).

Authentication

OctogenClient resolves your API key in this order:
  1. The api_key constructor argument, if provided.
  2. The OCTOGEN_PLATFORM_API_KEY environment variable.
  3. The deprecated OCTO_API_KEY environment variable. Reading it raises a DeprecationWarning once, and support will be removed. Set OCTOGEN_PLATFORM_API_KEY instead.
If none of these is set, the constructor raises MissingAPIKeyError immediately — before any network request is made. Every request then sends the key as Authorization: Bearer <api-key>.

Client constructor

These examples set the StoreRouter base URL explicitly, including when you use an SDK release that predates the domain migration. OctogenClient accepts the following keyword-only arguments:

Using the client as an async context manager

Use async with to ensure the underlying HTTP connection pool is closed when you are done:
If you manage the client’s lifetime yourself, call await client.aclose() when finished.

Methods

lookup_product

Resolves a product page URL from StoreRouter’s index or with on-demand product resolution. Set resolution_mode="index_only" when your integration requires indexed identity and catalog context.
Returns: MerchantProductUrlLookupResponse

retrieve_product and retrieve_products

Reads back products you already hold ids for, such as a uuid from search or lookup. Index-only and not billed. An older id resolves to the product; store the result’s uuid. A product the merchant stopped offering still comes back, with is_active=False and last_deactivated_at. retrieve_products takes 1–50 ids and returns one result per id, in request order. Requires octogen-ai-sdk 0.12.0 or later.
retrieve_product raises OctogenNotFoundError (detail == "product_not_found") for an unknown id, a product that left the index, or a product outside your key’s catalog access. In a batch, the same cases are status="not_found". Returns: ProductRetrieveResult / ProductRetrieveBatchResponse (results: list[ProductRetrieveResult])

search_products

Searches every catalog your key can access, or only the catalogs in catalogs. Each keyword controls one thing and is sent under the same wire name. See POST /products/search for the full field semantics. Returns: ProgrammaticProductSearchPage, a MerchantProductListPage subclass. Each MerchantProductListItem includes uuid, catalog_key, product_url, title, brand, current_price, original_price, primary_image, images, rating, is_active, optional match scores, and updated_at. It also carries the deprecated image_url. primary_image and each entry in images are MerchantProductImageMetadataView models with url, cdn_url, width, height, size_bytes, and mime_type. Prefer the hosted copy and fall back to the merchant URL:

Local validation

The SDK checks the contradictions the API would refuse and raises pydantic.ValidationError before sending a request:
  • understand=False, relax=True, or a non-empty omit_generated_facets without q. omit_generated_facets also requires understand to stay on, and so does relax=True unless at least one facet is sent with relaxable=True.
  • A facet name repeated within facets or exclude_facets, or a name in both facets and omit_generated_facets.
  • More than 50 entries in facets, exclude_facets, or omit_generated_facets.
  • A negative price or price_min > price_max.
  • Brand quality outside 1–6, or brand_quality_min > brand_quality_max.
  • similar_to_brands that is empty, has more than 10 names, or has a blank name.
An empty catalogs list or a blank key raises ValueError, and a bare string raises TypeError. The server remains the source of truth for everything else, such as unknown facet names.

Removed in 0.5.0

These keywords were deprecated in 0.4.0 and are gone in 0.5.0, because the API now rejects them with a 422. Passing one to search_products raises TypeError.
text_search_query’s retrieval tuning (search_id, ranking_text, embedding columns, similarity weights, search_after, browse_menu_uuid, compact_mode) has no replacement on /v1 search.

more_like_this_products

Finds products similar to a source product URL or UUID. Provide exactly one of source_url or source_uuid. Omit catalogs to search all active crawled catalogs, or pass 1–100 catalog keys to keep the results within those catalogs.
Returns: ProgrammaticMoreLikeThisResponse

Complete example

The following example searches all active crawled catalogs for women’s linen dresses and prints each result with its brand and price:
Use Facet objects to filter by brand, gender, color, category, and other attributes. Pass a list of facets to the facets parameter of search_products.
You can also pass plain dicts instead of Facet instances — the SDK coerces them automatically:
FacetName is a StrEnum with constants for all built-in facet fields: BRAND_NAME, GENDER, AGE_GROUPS, COLOR, COLOR_FAMILY, IS_ACTIVEWEAR, PRODUCT_TYPE, CATEGORY_PATH_DEPTH_0 through CATEGORY_PATH_DEPTH_6, and more. You can also pass a taxonomy attribute handle, such as fit, as a plain string. Use the bare handle: attribute_facets.fit is rejected. Facet values are canonical lowercase handles. See Facet names.

Pagination

When next_cursor is not None in a response, pass it back verbatim as cursor, with the same other arguments, to retrieve the following page. A cursor the API cannot use returns 400 with detail "invalid cursor"; restart from page 1 without cursor. Pages don’t overlap, but a product can repeat if the catalog changes between requests, so de-duplicate by uuid.

Error handling

All SDK errors inherit from OctogenError. HTTP errors inherit from OctogenAPIError, which exposes status_code, detail, and response attributes.
Raised when your API key is missing, malformed, or has been revoked. Check that OCTOGEN_PLATFORM_API_KEY is set correctly and that the key is still active in StoreRouter Platform.
Raised when a valid key attempts an action it is not authorized for — for example, accessing a catalog that has not been granted to your organization.
Raised when a catalog or product URL cannot be found. For lookup_product, verify the URL belongs to a catalog your key can access.
Raised when the API rejects a request due to invalid parameters. The detail attribute contains the validation error list from the API. search_products catches many invalid combinations locally and raises pydantic.ValidationError before sending a request.
Raised when the SDK cannot reach the API — for example, due to a network timeout or DNS failure. Does not have a status_code.
Catch the base OctogenAPIError to handle all HTTP errors in one place:
MissingAPIKeyError is raised by the constructor, not by a network call. It will surface at client creation time if neither api_key nor an API key environment variable is present.

BigQuery subscribe (optional)

If StoreRouter shares a catalog with you over BigQuery Analytics Hub, the SDK can subscribe to the listing and create a linked dataset in your own Google Cloud project, so you can query the catalog with SQL. See the Subscribe to a catalog in BigQuery guide for the full walkthrough. This helper uses your Google Cloud Application Default Credentials — not your OCTOGEN_PLATFORM_API_KEY — so it lives behind an optional bigquery extra:
This installs the octogen-bq-subscribe CLI (dry-run by default; --apply to subscribe) and the octogen-bq-autosubscribe cron helper for keeping linked datasets current as new listings become available:

subscribe_to_listing

A synchronous function (unlike the async OctogenClient). Idempotent — an existing subscription to the same listing in destination_project is returned as-is. Returns: BigQuerySubscriptionResult with listing_resource, linked_project, linked_dataset, state, already_subscribed, subscription_name, and a ready-to-run sample_query.
Two BigQuery error types extend OctogenError: OctogenBigQueryError (base) and OctogenBigQueryAccessPendingError, raised when StoreRouter’s IAM grant on the listing hasn’t propagated yet. Because the grant is asynchronous, catch the access-pending error and retry after a few minutes.

Brand directory, profiles, and browsing

Use Python SDK 0.16.0 or later for the lightweight profile contract. get_brand_details returns BrandDetailsView; it no longer returns coverage. Request that independently with get_brand_coverage.
The directory is complete and unpaginated. Article dates preserve their source precision. Navigation and top categories are recorded brand-wide metadata, not live inventory. Product rows and total respect your customer’s catalog scope. Follow next_offset through short or empty projected pages; total counts source rows. Offset 11976 is the final supported start. See brand browsing. OctogenNotFoundError means an unknown brand. A server error is a failure, not an empty directory or missing profile. Load coverage separately when the profile must remain available during a snapshot failure. For manual ETag revalidation, use the HTTP directory example.